What is Sheriff?

Sheriff is designed to prevent the illegal copying of software products, ensuring that they are operated within the terms of the software publisher's End User Licence Agreement (EULA). Software developers integrate Sheriff with their applications using the Sheriff Software Development Kit (SDK). The SDK includes classes and demo applications for Visual C++, Visual Basic, Visual FoxPro and Delphi so enabling the protection of a wide range of products, including applications, databases and spreadsheets. Sheriff 2.0 has introduced the facility to integrate Sheriff as an ActiveX control.

Sheriff offers flexibility, security & ease of implementation without the need to pay royalties or distribute dongles or key disks.

Flexibility

Sheriff provides a wide variety of software licensing schemes, including how long a trial will last, which features to enable and/or how many concurrent network users should have access. With a combination of these licensing schemes, publishers can distribute a single application package that serves as a demo, a trial application, a limited feature application or a full feature application.

Security

We believe that security is the most important part of any licensing system. Every part of Sheriff is securely protected against misuse or hacking. Within Sheriff the Licence Key and licence databases are dynamically encrypted, the communication channels between client and server are challenged and the Licence Generator is protected by Secret Codes against unauthorised access. Sheriff is simply the most secure licensing system in its class - see the Technical Introduction for further details.

Ease of Implementation

It requires minimum time and effort to protect a product with Sheriff - just four function calls are needed - while the authorisation of a licence requires only the exchange of the user's Reference Code and the publisher’s Licence Key.

  • When a user installs or uses the product for the first time, a Reference Code is generated.

  • The user informs the publisher of the Reference Code and the publisher generates a Licence Key (a numeric string).

  • The user enters the Licence Key and the product runs normally but is protected from illegal copying - it is bound to the user's hardware by means of a licence file. It is possible to export a licence to another hardware platform, such as a laptop, and to enable a specified number of users to share licences over a network.

Integration

How you integrate Sheriff with your application will depend upon your development environment.

Visual C++

You can call the Sheriff DLL from your application or you can use the static library. For further details please refer to the following topics:

  • Technical Overview
  • Developers' Guide

Java & Powerbuilder

Please ask us for further information.

All Others

You can call the Sheriff DLL from your application or you can use the ActiveX control. For further details please refer to the following topics:

  • Technical Overview
  • ActiveX


Guide to Help Topics

Technical Overview | A review of Sheriff's features and implementation.
Applications | The Demo Application [SlsDemo] provides a simple example of a Sheriff-protected progam. The Product ID & Secret Codes Generator [SlsPsn] is used by registered Sheriff software developers to generate unique Product IDs & Serial Codes for their applications (normally one Serial Number per application is required). The Licence Generator [SlsGen] is used by publishers of Sheriff-protected products to generate licence keys for their users. The Administrator [SlsAdmin] is used by end users of Sheriff-protected products to manage their licence keys.
Developers' Guide & ActiveX Control | For software developers who wish to integrate the Sheriff Licensing System into their applications via DLL [topic Developers' Guide] or via ActiveX [topic ActiveX Control].
Sheriff API Reference | Details of data structures and functions in the Sheriff API.
FAQ | The answers to frequently asked questions.
Licence Agreement | The End User Licence Agreement (EULA) for the Sheriff SDK and the provision of support & maintenance.


Contact Information

Address: | Acudata Limited Clarendon House Shenley Road Borehamood Hertfordshire WD6 1AG England
Web: | www.sheriff-software.com
Email: | info@sheriff-software.com
Tel: | +44 181 905 2552
Fax: | +44 181 959 8583


Introduction

Overview

Sheriff adopts a client-server architecture; the client is the application to be protected, the server is the Sheriff DLL. When an application executes it provides Sheriff with information such as the Product ID and user name, which Sheriff validates against its licence database. If validation is successful the application runs normally, if unsuccessful an application can either exit or continue running in 'demo' mode.

While an application is running it periodically communicates with Sheriff to ensure the currency of the database; this is often referred to as a 'heartbeating'. Before an application exits it notifies Sheriff to free-up its resources, making them available for the next user. Should an application terminate abnormally Sheriff automatically reclaims the licence.

Architecture

  1. Client. This is the application you wish to protect. Client interacts with the licence server through API functions.

  2. Server. This is the Sheriff DLL (SlsApi.dll) which provides licensing services through its API functions.

  3. Registry. Sheriff utilises the Windows Registry to keep track of various licences and the location of licence databases on the user’s machine.

  4. Sheriff Licence Database. This maintains information such as licence policy, licence usage and user’s activities.

Applications

Applications are provided for the vendor and end user:

  • Sheriff Licence Key Generator (SlsGen.exe)
  • Licence Administrator (SlsAdmin.exe).
The Licence Key Generator is used by software vendors to create keys for their customers, while the Administrator enables end users to manage their licence keys. Note that the full functionality of these applications is replicated in the Sheriff API (via SlsApi and SlsApiEx) enabling a very high degree of customisation.


Key Features

  • Machine Locking
  • Comprehensive Licence Policy
  • Portable Licence
  • Network Licence
  • Licence Reclaim
  • Administration Tools

Machine Locking

Machine Locking ensures that an application will only execute on a PC or network against a valid licence. The licence cannot be copied to another machine nor can it be backed up and restored on the same machine. To achieve this, Sheriff employs an advanced proprietary algorithm for generating a unique 'fingerprint' of the machine where the licence database resides, as well as a unique "fingerprint" of the licence database itself.

Comprehensive Licence Policy

Sheriff offers the following licensing options:

  1. Day Metering
  2. Unit Metering
  3. Expiration Control
  4. Concurrency Control
  5. Feature Access Control
  6. Reusable Key

Day Metering enforces the lifespan of the application from the day of installation.

Unit Metering enables software publishers to decide what actions are chargeable and how they are charged.

Expiration Control forces an application to expire ('bomb out') on a specified date.

Concurrency limits the maximum number of concurrent users on a network. Sheriff treats many invocations of an application by the same user on the same computer as a single user.

Feature Access Control enables software publishers to categorise features in their products into many different levels and permits users to access only the levels that they have subscribed to.

Reusable Key enables a user to regenerate the licence database on the original machine without reference to the publisher in the event that the database file is damaged or overwritten. A Reusable Key is only issued when metering or expiration controls are not used.

Portable Licence

The portable licensing facility enables the user to export a licence from one machine to another, such as a portable PC (this facility can be disabled when issuing the licence key.

Normally, when a licence has been exported the protected application cannot execute on the original machine until the licence is re-imported, however the user can define the features of the exported licence within the terms of the original licence policy. So, for example, the exported licence may be set to expire after seven days and when it does the licence is automatically restored on the original machine.

Network Licence

Sheriff can be run on a network with a single licence database; typically this is installed on a file server. See "Networking" topic for further details.

Licence Reclaim

If a networked application terminates abnormally without notifying Sheriff, its licence also dies.

Sheriff will automatically reclaim the dead licence after the expiration of a predefined 'reclaim time' (which must be longer than the 'heart-beat' time). Once a licence has been reclaimed by Sheriff it can be claimed by another network user, however should the terminated application request a licence within the 'reclaim time' Sheriff will revive the dead licence immediately for that application.

Administration Tools

Sheriff provides a Licence Key Generator program (SlsGen.exe) for publishers. The Licence Key Generator logs all the licence keys issued together with user information.

The Sheriff Licence Administrator program (SlsAdmin.exe) enables end users to manage the licences of their Sheriff-protected applications, which may come from different publishers. The Licence Administrator can also be used to monitor licence usage on a network, such as who is logged on and what licence is being used, as well as the current state of licences, the renewal of licences and the import/export of licences.


Security

Features

  • Encrypted Licence Key
  • Encrypted Licence Database
  • Encrypted and Challenged Communication Channels
  • Anti-tampering Measures
  • Anti-debug Measures
  • Protected Licence Key Generator with Secrets

Encrypted Licence Key

The Sheriff Licence Key is dynamically encrypted, which means that the Licence Key changes every time it is generated even with the same Reference Code and licence policies. This is to prevent the Licence Key from being dissected. The Licence Key as well as the Reference Code are self-checked; any bit change to them causes them to become invalid.

Encrypted Licence database

The Sheriff licence database is encrypted and cannot be modified.

Encrypted and Challenged Communication Channels

The communication channel between an application and Sheriff is encrypted to prevent parameters being monitored or altered en-route. In addition, Sheriff employs a challenge/response protocol in calls between the client and the server. It provides a very reliable way for Sheriff and an application to verify that the other is a legitimate party.

Anti-tampering Measures

Comprehensive anti-tampering facilities are built into Sheriff, including:

  1. System clock verification (E.g. cannot be wound back to gain extra days).
  2. Licence database cannot be backed up and restored to gain extra units.
  3. Hardware parameters cannot be emulated to duplicate licence for unauthorised machines.

Anti-debug Measures

Built-in anti-debug facilities prevent Sheriff codes from being traced and dissected.

Protected Licence Key Generator with Secrets

The Sheriff Licence Key Generator cannot be used to generate unauthorised Licence Keys. To generate Licence Keys for a product, a set of Secret Codes is required and each product has its own set of Secret Codes.


How to Protect an Application

To protect an application with Sheriff, access to the source code is required. However, it is very quick and easy to implement protection; a typical implementation requires four API function calls.

The Sheriff SDK provides ready-to-use template classes and demos for the popular Windows programming languages Visual C++, Visual Basic, Visual FoxPro and Delphi. Sheriff can also be implemented as an ActiveX control.

The Sheriff DLL offers a number of advantages over a shell system:

  • It provides more secure protection.

  • It supports more complex licence policies, such as metering, as well as all the basic functions.

  • Publishers can use their own front-end instead of fixed dialog boxes. In the example below, the screen presented to the user is entirely proprietary - no mention of Sheriff. This also gives the freedom to present any licence-related information and means that the product can support multiple languages.


How to Generate a Licence

sequence.gif - 4440 Bytes

To enable a Sheriff-protected application the end user will require a Licence Key from the publisher. To obtain a Licence Key the end user must inform the publisher of the unique Reference Code; this is usually generated when the application is installed. The Reference Code and Licence Key can be exchanged by phone, fax, email or the Licence Key can be generated automatically on an NT server and displayed on a web page. Reference Codes are also generated when licences are upgraded or when new licences are purchased.

Once the Reference Code has been generated it is valid until the corresponding Licence Key is received and entered, allowing publishers and end to users to work in different time zones. This also gives publishers the option to check the details of a new customer before releasing the Licence Key.

The publisher enters the Reference Code into the Sheriff Licence Key Generator and chooses the appropriate features for the Licence Policy (E.g. the licence to expire on a certain date). The Sheriff Licence Generator then generates a unique one-time Licence Key for the user.

Each pair of Reference Codes and Licence Keys is unique and machine-specific. The Reference Code cannot be regenerated; the Licence Key cannot be reused on the original machine or used on any other machine.

When using Expiry Date metering it is possible to generate a ‘Reusable Reference Code’. This removes the need for contact with the user since one Reference Code, within certain limitations, lasts indefinitely. Using this option you can generate new expiry-dated licence keys as needed.

Further details on generating a licence key are given in the "Applications | Licence Generator" topic.


Networking

The network can be a local or wide area network, which can span time zones. Sheriff can operate on any type of network; note that the application requires write access to the Sheriff licence database so the licence file should be in a shared location - either a mapped drive or else a drive that is accessible via UNC.

The maximum number of concurrent users can be specified and you can monitor active programs and which active users have access to them. You can also suspend an active user at any time although normally you will only do this you when you have reached the limit of authorised concurrent licences and you wish to grant access to another user.

The product has to be registered on every workstation on which it is to run. This task is performed using the Sheriff Administrator - see the Sheriff Licence Administrator topic for further details on administering a Sheriff-protected application on a network.

Note that a licence may be defined as "Standalone" in which case use of the protected application is restricted to the machine on which the licence resides.


Requirements

System

Windows 95/98 & Windows NT 4.0

Any Network Operating System

Language Support

Sheriff supports any Windows programming language that can call a Windows DLL. The Sheriff SDK provides the source codes of template classes and demo applications for Visual C++, Visual Basic, Visual FoxPro and Delphi.


Glossary

Control - Concurrent User

Defines the maximum number of network users that can access the product simultaneously. The identity of those users can be controlled from the Sheriff Licence Administrator (SlsAdmin.exe)

Control - Expiry

Defines the date on which a licence expires.

Control - Feature Access

Defines which features of a product are enabled.

EULA

End User Licence Agreement. The agreement between software publishers and their customers.

Licence Administrator (SlsAdmin.exe)

A Sheriff application that enables end users to manage their software licences (Eg. to Import a licence from another computer or to monitor concurrent users).

Licence Import

A means of importing a licence from another computer. See the Sheriff Licence Administrator help for details.

Licence Export

A means of exporting a licence to another computer. This feature can be disabled in Options i.e. you can disable the user's ability to export a licence key to another machine, so locking the licence to one machine only. See the Sheriff Licence Administrator help for details of how to export a licence key.

Licence Database

Collection of three files installed on the end user's machine, including the Licence File.

Licence File

File created on the end user's machine that contains the Licence Policy. The file must be present on the end user's machine for a Sheriff-protected application to execute.

Licence Key

The code issued to the end user by the publisher, and embedded in the Licence File, that enables a Sheriff-protected application to execute in accordance with the terms of the Licence Policy.

Licence Key Generator (SlsGen.exe)

Sheriff application used by publishers to generate Licence Keys.

Licence Policy

The features and limitations of the end user's licence as defined by the publisher and passed to the user in the Licence Key.

Log File

Details of all licences issued are appended to the log (SlsGen.log). Comments may be added to the log directly from the Licence Generator.

Metering - Unit

Method of limiting the number of times a Sheriff-protected application is executed by reference to the consumption of units that are defined by the publisher.

Metering - Day

Method of limiting the number of days in which a Sheriff-protected application is executed.

Portable Licences

A licence can be imported to another machine using the Sheriff Licence Administrator's Import facility.

Product ID

A unique code used by the publisher that identifies a Sheriff-protected product and distinguishes it from other Sheriff-protected products. A unique Product ID is generated from a Serial Number.

Product ID & Secret Codes Generator (SlsPsn.exe)

Enables the publisher to generate a unique Product ID and Secret Codes from a Serial Number.

Publisher Data for User

Supplements the Licence Key. The Licence Key is compulsory whereas publisher data is optional. If a publisher feels that the Licence Key does not provide enough features, the Licence Key can be supplemented by Publisher Data. Publisher Data is saved with the Licence Key and is in effect an an extension to the Feature Access Key facility. However, unlike the Feature Access Key, Publisher Data can be up to 32 bytes long and is entered by the user at the time of entering the Licence Key. The Publisher Data may be saved or retrieved by using the appropriate Sheriff API functions.

Reference Code

Code provided by the end user when enabling a Sheriff-protected application. Publisher requires Reference Code in order to generate a Licence Key.

Reusable Key

A Licence Key that can be used on the same machine an unlimited number of times. With a Reusable Key the end user can restore the original licence to the same machine if the Licence File is lost or damaged by accident (not used when Metering is implemented). NB. A new key will be required if the hard disk has been reformatted.

Reusable Reference Code

This option is only available when Expiry Date metering has been selected. It is used when you want to be able to extend the date on which the licence will expire without first contacting the user for a new Reference Code.

Secret Codes - Standard

Secret Codes are required to generate unique Licence Keys for a product. The Secret Codes are entered into the Sheriff Licence Key Generator and enable a publisher to generate Licence Keys for his product alone.

Secret Codes - Encrypted

As additional protection against hacking the publisher may prefer to embed encrypted Secret Codes in his product (the Standard Secret Codes are entered into the Sheriff Licence Key Generator).

Serial Number

A unique number issued to the publisher to enable the generation of a Product ID and Secret Codes (using the Product ID & Secret Codes Generator).

Status Code

The Verify Status Code feature enables a publisher to check the current status of a user's licence. In the Administrator, when a licence is being registered/authorised, a message box underneath the Reference Code shows the current (or, if not available, previous) licence status. To verify the Status Code, the publisher requests the user to provide that code and then, in the Licence Generator, selects Tools|Verify Status Code and keys in the code. The licence status is displayed.

System Clock Verification

A feature of Sheriff's anti-tampering facilities. Ensures that day metering & expiry date control cannot be bypassed.

Termination Code

When a user manually terminates a licence using the Sheriff Licence Administrator a Termination Code is displayed. The publisher can verify this code using the Sheriff Licence Key Generator.


Introduction

This document serves as a guide for software developers who wish to integrate the Sheriff Licensing System into their application in order to protect against illegal copying; for details of data structures and functions in the Sheriff API please refer to the Sheriff API Reference.

The Sheriff API is provided as Windows Dynamic Link Libraries. For VC++ applications, a static link library is also provided. Any Window programming language capable of calling a standard Windows DLL can work with the Sheriff API. The Sheriff SDK provides direct support for Visual C++, Visual Basic, Visual FoxPro and Delphi with API interfaces and API classes.

For simplicity, API functions for C++ are used throughout this document, unless it is explicitly stated otherwise. However API interfaces and classes in Visual Basic, Visual FoxPro and Delphi are very similar to their C++ counterparts.


SDK Components: File Names & Locations

SDK Components

API Libraries
Sheriff Dynamic Link Library | SlsApi.dll | \SHERIFF\API
Link Library for Slsapi.dll | SlsApi.lib | \SHERIFF\API
Sheriff Extended DLL | SlsApiEx.dll | \SHERIFF\API
Link Library for SlsApiEx.dll | SlsApiEx.lib | \SHERIFF\API
Visual C++ Interface
Sheriff API release build with multithread | SlsLib.lib | \SHERIFF\API\VC
Sheriff API debug build with multithread | SlsLibD.lib | \SHERIFF\API\VC
Sheriff Extended API release build with multithread | SlsLibEx.lib | \SHERIFF\API\VC
Sheriff Extended API debug build with multithread | SlsLibExD.lib | \SHERIFF\API\VC
Header file for extended library | SlsApiEx.h | \SHERIFF\API\VC
API Data Structure | lictype.h | \SHERIFF\API\VC
API Constant Definition | licdefs.h | \SHERIFF\API\VC
API Error Codes | licscode.h | \SHERIFF\API\VC
C++ API Interface | SlsApi.h | \SHERIFF\API\VC
C++ API Class Header | Sheriff.h | \SHERIFF\API\VC
C++ API Class Implementation | Sheriff.cpp | \SHERIFF\API\VC
Header for Other C++ Compilers | licnonvc.h | \SHERIFF\API\VC
Visual Basic Interface
VB API Interface | SlsApi.bas | \SHERIFF\API\VB
VB API Class | CSheriff.cls | \SHERIFF\API\VB
Interface to extended library | SlsApiEx.bas | \SHERIFF\API\VB
Visual FoxPro Interface
VFP API Interface & API ErrorCodes | SlsApi.h | \SHERIFF\API\VFP
VFP API Class | Sheriff.prg | \SHERIFF\API\VFP
Helper file | Convertapi.prg | \SHERIFF\API\VFP
Delphi Interface
Delphi API Interface | SlsApi.pas | \SHERIFF\API\DELPHI
Delphi API Class | CSheriff.pas | \SHERIFF\API\DELPHI
Extended API | SlsApiEx.pas | \SHERIFF\API\DELPHI
Applications for Publishers
Product ID & Secret Codes Generator | SlsPsn.exe | \SHERIFF\APPS
Product ID & Secret Codes Generator Help | SlsPsn.chm | \SHERIFF\APPS
Licence Key Generator | SlsGen.exe | \SHERIFF\APPS
Licence Key Generator Help | SlsGen.chm | \SHERIFF\APPS
Applications for End Users
Adminstrator | SlsAdmin.exe | \SHERIFF\APPS
Adminstrator Help | SlsAdmin.chm | \SHERIFF\APPS
Adminstrator Help Docs |  | \SHERIFF\APPS\SLSADMIN DOCS
Demonstrations
Visual C++ Source Code |  | \SHERIFF\DEMO SOURCE\VC
Visual Basic Source Code |  | \SHERIFF\DEMO SOURCE\VB
Visual FoxPro Source Code |  | \SHERIFF\DEMO SOURCE\VFP
Delphi Source Code |  | \SHERIFF\DEMO SOURCE\DELPHI
Demo Application |  | \SHERIFF\DEMO APP


Quick Start

Sheriff identifies each application by its unique Product ID. A Product ID and set of Secret Codes will be used in the Sheriff Licence Key Generator application and also in your code. The Product ID and Secret Codes are generated from the Product Serial Number using the Sheriff Product ID & Serial Number Generator (SlsPsn.exe). You can obtain your own unique Product Serial Number from your Sheriff distributor. However, if you are using Sheriff for evaluation purposes, you can use the following evaluation Product ID and Secret Codes:

Product ID: 9758-3050-1918-9292-6466
Secret Codes: 0763-1985-3207-6621
1854-2076-4198-7532
2482-1593-2604-4927
3739-0628-9517-9618

Encrypted Secret Codes:

      SLS_SECRET g_arySecrets[]=

{

          {0x76,0x3E,0x6D,0x36,0x14,0x14,0x6D,0xB8,0x1D,0xCA,0xF3,

          0xD5,0x34,0x2D,0x08,0xBC,0x14,0x31}, {0x00,0xB7,0x17,0x00,0x43,0xFC,0xC0,0x7F,0x8F,0xA2,0x22,

          0xD2,0x1B,0x62,0xB3,0xDE,0x95,0x3F}, {0xAC,0x2E,0x39,0x6F,0x45,0xD5,0x41,0x11,0x43,0x41,0x2B,

          0x75,0x9C,0xB2,0x67,0x6E,0x14,0x02}, {0x79,0x52,0x9A,0x49,0x97,0x8B,0x1C,0x15,0x64,0xB7,0xBE,

          0x6C,0x7F,0x18,0xC3,0x4E,0x78,0x87},

      };

Please note that you should not use the above Product ID and Secret Codes with your released product - they are used by everyone who is evaluating Sheriff. When you have obtained a Product Serial Number you should keep it secret.

If you intend to call API functions directly from SLSAPI.DLL, you need to include SLSAPI.H in your application, such as in stdafx.h header file with Visual C++ applications. If you wish to use CSheriff class however, you need to include Sheriff.h in your application. SLSAPI.LIB is provided to link SLSAPI statically into your application.

Only SLSAPI.DLL need be distributed with your application.

There are three steps involved in protecting an application with Sheriff:

  1. Product Registration
  2. Licence Authorisation
  3. Runtime Implementation

These steps are explained in detail in topics that follow.


Registering a Product

First of all, you need to register your application on the end user’s machine. Product registration requires the Product ID, Product Name and Licence Path. Products are distinguished by their Product IDs - each product has a unique ID. The product name is only used for administration purposes, for example the Sheriff Administrator application (SlsAdmin.exe) displays the names of products currently running in its 'monitor' window. The licence path tells Sheriff where the licence files reside.

Once a product is registered this information will be kept in Windows Registry in the following location:

HKEY_LOCAL_MACHINE\SOFTWARE\ACUDATA\SHERIFF\PRODUCTID

Sheriff uses the Windows Registry to keep track of which products are registered on the machine and where their licences reside.

There are two ways of registering a product, manually or programmatically:

  1. To register your product manually, end users will have to run the Sheriff Administrator (SlsAdmin.exe) to register your product. Please refer to SlsAdmin online help for details.

  2. To register your product programmatically, call SLS_Register. This step is typically carried out by your installation program, although you can register your product from your main application before you call other API functions.

Once your product is registered on the machine you do not need to repeat it, although there is no harm in repeating a registration.


 Licensing a Product

After your product is registered on the end user’s machine you need to license the product by issuing the user with a Licence Key.

The end user exchanges a Reference Code for the Licence Key. The Reference Code is unique to your product and the machine it is installed on and consists of 24 digits, with the first 12 digits being the machine signature, the next 4 digits being the product signature and the last 8 digits being the run-time signature.

There are two ways of authorising a licence: by using the Sheriff Administrator or by using your application:

  1. The end user will run Sheriff Administrator to generate a one-time user Reference Code and give it to you in exchange for the Licence Key. You use the Sheriff Licence Key Generator (SlsGen) to generate a Licence Key for the user, who enters the Licence Key in the Sheriff Administrator (SlsAdmin). Details can be found in the help topics for SlsAdmin and SlsGen.

  2. If you wish to present your own authorisation dialog boxes in order to keep a consistent 'look and feel' - and to make the authorisation procedure more convenient for your users - you will need to call two API functions, SLS_GetReference and SLS_SetLicence.

    SLS_GetReference is called to generate the user's Reference Code. Once the Reference Code has been exchanged for a Licence Key then SLS_Licence is called to authorise the Licence Key.

    Authorisation should take place the first time the user installs your application or any time your application detects that there is either no licence on the machine or an existing licence has become invalid (E.g. because it has expired). When your application calls SLS_Request to request a valid licence, SLS_Request returns an error if the licence requested is invalid or undefined.

    You can also call SLS_QueryLicenceInfo to obtain the current state of a licence including detailed licence policies and licence usage such as the number of days left or the number of users using the licence.


Runtime Implementation

To protect your application with Sheriff you need to implement three functions: Requesting, Updating and Releasing. Each function only involves one API call.

Requesting

In your application, the first thing you want to do is to check that your licence is still valid. In other words, you need to request Sheriff to grant permission to run your application in the appropriate mode. SLS_Request is the function to call, it will return with various error codes if Sheriff detects that there is no valid licence on the machine. It is up to your application to take appropriate action should this happen. The demo application provides some examples.

Updating

While your application is running you need to periodically call SLS_Update to update Sheriff with the latest licence usage information, Sheriff will also update your application with the latest licence state. Updating performs two important tasks:

  • Sheriff needs to check whether the application is still up and running in order to decide whether an allocated licence resource should be reclaimed.
  • Updating ensures that the licence is valid throughout the time the application is running. This is particularly important if unit metering is being used.

Updating is often referred as 'heartbeating', to make client and server heat-beat at the same pace. As explained, updating is related to licence reclaiming. If a running application fails to update Sheriff within the predefined reclaim time, Sheriff will decide that the application is dead (E.g. crashed or deadlocked). By default, the reclaim time is set to 15 minutes; you can set your own reclaim time by calling SLS_SetReclaimTime.

Therefore the updating interval should be shorter than the reclaim time. Typically you will set up a timer in your application and call SLS_Update in the timer message handler.

Releasing

Before your application exits, you need to call SLS_Release to notify Sheriff to release the licence resource so that it will be ready for the next application. Failing to call SLS_Release will result in a dead licence and there may be some delay before it can be automatically reclaimed by Sheriff.


API Challenge

Sheriff employs a so-called challenge mechanism to provide extra security. Your application can challenge Sheriff to verify that the it is original and has not been tampered with; Sheriff can also challenge back to verify that the calling application is original and has not been tampered with. Challenge also ensures that the parameters cannot be altered en-route.

Challenge can be enabled to add an extra level of security to the following functions: SLS_License, SLS_Request, SLS_Update and SLS_Release. To enable the challenge mode, you need to set the challenge protocol to SLS_BASIC_PROTOCOL. For example:

SLS_CHALLENGE Challenge;

Challenge.Protocol=SLS_BASIC_PROTOCOL;

Challenge.Size=sizeof(SLS_CHALLDATA);

Challenge.ChallengeData.SecretIndex=nSecretIndex;

Challenge.ChallengeData.Random=nRandom;

If you prefer not to enable challenge mode, all you need to do is to set the challenge protocol to SLS_NO_PROTOCOL. But please note that challenge must be implemented in calling function SLS_License.

To create a challenge, call SLS_CreateChallenge with your product Secret Codes and the input data stream; to verify a challenge, call SLS_VerifyChallenge.

If CSheriff class is used, calling SetSecrets method with your product Secret Codes will automatically enable the challenge mode. Otherwise, it is not enabled.


Error Handling

Should any API function call fail, it returns an error code or status code other than SLS_SUCCESS. A full list of the status codes can be found in the topic "API Reference | SlsApi Status Codes". To obtain the error message you call SLS_GetErrorMessage with the error code.


Standalone & Network Licences.

A standalone licence is a licence for a single user. The protected application can only be run on the machine on which the standalone licence is installed and cannot be shared by network users on different machines. A standalone licence cannot be shared by two operating systems running on a dual-boot PC.

A network licence permits more than a single user and its licence database is usually located in a shared network file server. The maximum number of concurrent users are defined using the Sheriff Licence Key Generator application (SlsGen.exe). Users also need read and write access to the licence database.


Using Sheriff on Networks.

Sheriff is designed to protect applications running on networks. In particular, the concurrency limit is used to control the maximum number of users who can simultaneously access a Sheriff-protected application.

To use Sheriff on networks, you need only one licence database installed on the network system. Typically the licence database will be sitting on a file server which is accessible to all of the users who want to run the protected application. One important thing to note is that users should be allowed to have write access to the licence database, because Sheriff needs to be able to update it at any time.

Once a licence is installed on a network, applications running from workstations should register their products with the licence path pointing to the location where the licence database has been installed (see topic "Registering a Product" for details of how to register a product).


Web Enabled Licence Key Distribution

Overview

Licence Keys are normally distributed via phone calls, faxes, emails etc. However if you plan to set up an Internet service to distribute your Licence Keys, Sheriff provides facilities in its extended library, SlsApiEx.DLL. The Sheriff extended library is only for publishers; you should not distribute it with your application.

There is only one function in the extended library that you need to call: SLS_GenerateLicenceKey. When calling this function you provide details of your Product ID, Product Secret Codes, the user’s Reference Code and the Licence Policies you wish to issue.

Procedure

Your web page should contain an HTML form with fields similar to those in the Sheriff Licence Generator application (SlsGen.exe) such as Product ID, User Name, Reference Code and a list of options. There should be a means of displaying the generated Licence Key to the user, although the exact configuration is up to you.

When a user enters a Reference Code and clicks on a Generate button a CGI script should verify the form by calling SLS_GenerateLicenceKey, which will then return a Licence Key. In summary:

  1. You will need to have the Sheriff extended library (SlsApiEx.DLL) installed on your server, which will necessarily be running under Windows 95/98/NT.

  2. Create a form on your web (with a minimum of one field, so that the user can input their Reference Code).

  3. Your web server calls a CGI script, so that a Licence Key is generated when the form is submitted (i.e. The CGI script will call the SlsGenerateLicenceKey function from the extended library).

Example

The following CGI example is written in C++

void Generatekey(const char *pszReferenceCode)
{
char szKey[128];
SLS_LICENCE TrialLicence;
memset(&TrialLicence,0,sizeof(SLS_LICENCE));
TrialLicence.Type =
SLS_TYPE_TIME_METER|SLS_TYPE_CONCURRENCY|SLS_TYPE
_STANDALONE;
TrialLicence.Meter=30; //30 day
TrialLicence.CoUsers=1; //1 user only

int
ret=SLS_GenerateLicenceKey(g_szProductID,g_arySecrets,4,
pszReferenceCode,
&TrialLicence,
szKey);
}


Make Trial Applications.

Making Trial Applications

Trial applications are often of limited . There are two kinds of time limitation, one is to limit the number of days starting from the date of installation, another is to set an expiry date. With Sheriff you can use Day Metering and/or Expiry Control to control your application and make it a trail application. Once the trial period has expired, and the end user wishes to continue using your application with full features, you can issue an appropriate Licence Key to the user without changing your application.

Initially, there is the issue of distributing a trial Licence Key (i.e. a Licence Key with limitations). As discussed before, distribution involves an exchange of a user’s Reference Code and the publisher’s Licence Key, which can be done via phone calls, faxes, emails, etc. However, if you do not want to get involved in the distribution of trial Licence Keys you can automate this procedure by calling a couple of Sheriff API functions. The function to issue a licence key without intervention between users and publishers is SLS_License Challenge is required to call this function otherwise it would be subject to abuse.

Another issue is how to prevent the application from being re-installed after the trial period in the attempt to gain extra time, which can be done by calling SLS_IsProductInstalled. In your application, you need to call SLS_IsProductInstalled before you call SLS_License. SLS_IsProductInstalled detects whether a specified product has been previously installed and used. However this does not prevent a product from being installed on another machine.

To prevent users from installing a trial on more than one machine, yet at the same time without the need to manually issue a trial Licence Key, the ideal solution is to set up a Web page to distribute the trial Licence Keys (see topic "Distributing Keys via the Web").


 Make Demo Applications

Demo applications offer limited features to end users. With Sheriff, a demo application can be a full-featured application yet only allow limited access.

With feature access control, you can make your demo application more realistic by allowing different users to have access to different levels of features in your application.

Typically, Sheriff-protected applications run in demo mode if there is no valid licence present on the end user’s machine.


CSheriff Class Reference.

CSheriff is a shrink-wrapper class of the Sheriff Licensing System API. The reference lists the member methods and explains in brief their functionality. Detailed discussion on API functions can be found in Sheriff API Reference.

Construction

CSheriff(LPCTSTR lpszProductID,LPCTSTR lpszUserName);

Construct a CSheriff object. lpszProductID points to a null-terminated string which identifies the product, lpszUserName points to a null-terminate string containing the user’s name.

Set Product Secrets

Void SetSecrets(SLS_SECRET *parySecrets,int nSizeSecrets=4);

Sets Product Secret Codes. parySecrets points to an array of secrets, by default the size of the array is 4. Product Secrets are required only if you want to implement challenge protocol.

Example:

SLS_SECRET Secrets[4]=

{

      "0763-1985-3207-6621

      "1854-2076-4198-7532

      "2482-1593-2604-4927

      "3739-0628-9517-9618

};

CSheriff *pSheriff=new CSheriff("9758-3050-1918-9292-6466","John Smith");

Sheriff->SetSecrets(Secrets);

Get User Reference Code

BOOL GetReference(CString &strReference);

Returns a one-time user reference code.

Authorise Licence Key

BOOL SetLicence(LPCSTR pszReference,LPCTSTR lpszLicenceKey);

Authorise licence key on the user’s machine. Reference must be provided through pszReference which is returned by calling GetReference.

Register Product

BOOL Register(LPCTSTR lpszProductName, LPCTSTR lpszLicencePath);

Registers a new product on the user’s machine. l pszProductName points to a string identifying the product’s name, lpszLicencePath points to a full path where licence files will be stored or have been stored.

License Product Programmatically

BOOL License(SLS_LICENCE Licence);

License is called to issue a licence from the application without user’s intervention. The difference between SetLicence and License is that SetLicence requires a Reference Code and Licence Key, whereas License can issue a licence straight away. SetLicence must be called in challenge mode. SetLicence is often called once by application installation program to issue a trial licence.

Request Licence to Run the Application

BOOL Request(SLS_REQUEST Request,SLS_PERMIT &Permit);

Request is called by the application to apply for permission to run the application.

Update Licence State

BOOL Update(SLS_UPDATE Update,SLS_PERMIT &Permit);

Update is called periodically by the application to notify Sheriff that the licence is still being used and also update Sheriff on the usage of the licence.

Release Licence

BOOL Release(SLS_RELEASE Release);

Release is called by the application to notify Sheriff that the application exits. Sheriff will then release the licence and make it ready to be taken by other applications.

Succeeded or Failed?

BOOL Succeeded();

Succeeded indicates whether the last function call is successful or not.

Get Last Error Code

HRESULT GetLastError();

Returns the error code caused by last operation.

Get Last Error Message

void GetLastErrorMessage(CString &strError);

Returns the last error message.


Introduction to ActiveX Control

Introduction to Sheriff ActiveX Control

The Sheriff ActiveX Control enables you to protect your applications very easily while still benefiting from Sheriff's high level of security and comprehensive features. This guide leads you through the integration of the Sheriff ActiveX Control with a VB application; it also demonstrates various ways of using Sheriff to protect your applications. Although this guide uses Visual Basic for demonstration purposes, the procedure should be more or less similar in other programming languages such as VBA or Delphi.

The Sheriff ActiveX Control is designed to be used in two modes:

  1. Automatic Mode you can protect your application with minimal programming. In this mode, Sheriff controls the pace of protection and fires the necessary events that your application should handle.

  2. Advanced Mode: Sheriff acts in passive way and let your application control the pace of protection.
Control Installation
Before you can use any ActiveX control you need to register it with the Windows operating system. To register Sheriff ActiveX control, run the following command:

regsvr32 sheriff.dll

Once the control is registered, you can then add the component to your toolbox or palette:

  • Visual Basic: Click on Project/Components, select Sheriff Licensing Control and press OK. The Sheriff control will appear on toolbox.

  • Delphi: Click on Component/Import ActiveX Control. Select Sheriff Licensing Control and press Install, then OK. The Sheriff control should appear in ActiveX palette.


 Automatic Mode Quick Start

We’ll demonstrate how easy it is to create a demo/trial application with the Sheriff ActiveX Control.

Step 1

From the toolbox, drag and drop a Sheriff ActiveX control anywhere in your application’s main form. Since Sheriff will be acting as an invisible control, turn the "Visible" property to "False".

Figure 1 below shows the properties of the Sheriff control.

Fig. 1

As you can see from the Figure 1, Sheriff categorises its properties into three types: Company Info, Product Info and Trial License. You can set those properties in the Properties Inspector window, as shown in Figure 1. Or you can set properties in with the property pages that Sheriff also provides.

Step 2

In the Property Inspector window, double click on "(Custom)". You will now see the property pages; click on the Product Info tab (see Figure 2 below).

Fig. 2

There are three options you need to set: Auto Trial, Auto Authorize and Auto Renew.

  1. With Auto Trial on, Sheriff will detect if the application has ever been licensed on the machine on which the application is being executed. If the application has not been licensed, Sheriff will automatically issue a trial licence that is pre-defined by the application’s publisher. To define the trial licence, click on the "Trial License" tab as discussed in step 3.

  2. With Auto Authorize on, Sheriff will also detect if the application is licensed on the machine. If the machine is not licensed, instead of automatically issuing a trial licence, Sheriff will present a licensing dialog box to the end user as shown in Figure 5. Company information such as company name and address etc can be set in the "Company Info" property page, as discussed in step 4.

  3. Similar to Auto Authorize, as soon as the application’s licence expires Sheriff will automatically present a renewing dialog box to the end user and asks the user to renew his licence with the application’s publisher.

Step 3

If, in Step 2, you decided to let Sheriff automatically issue a trial licence you need to define your trial licence.

Click on the "Trial License" tab to bring up the licence properties that you can defined for your trial licence (see Figure 3 below):

Fig 3.

Step 4

If, in Step 2, you decided to let Sheriff automatically handle licence authorisation and/or renewal with its own dialog boxes, then you need to set up your company’s information (to be displayed in the licence authorisation and renewal dialog boxes).

Click on the "Company Info" to display the property page (see Figure 4 below):

Fig. 4

Fig. 5

Step 5

Now that you have decided your licensing options, defined your trial licence and filled up your company information, it is time to write some code to put your application under Sheriff’s protection.

To run Sheriff in the Automatic Mode, the minumum requirement is one method you need to call and one event you need to handle.

The method to call is CheckLicence. Edit the form load event of your application main form and enter the following code:

Private Sub Form_Load()
   Sheriff1.CheckLicence
End Sub

Step 6

We’re almost done apart from one event from Sheriff that you need to handle.

If you have decided to go for Auto Trial, you need to handleOnChallengeevent. Sheriff fires upOnChallengebefore it can issue a trial licence to verify the identity of the application

Add OnChallenge event handler to the main form and enter the following codes:

Private Sub Sheriff1_OnChallenge(ByVal ChallengingData As String, ByRef ChallengedData As String)
   'we have to support challenge
   Dim Challenger As Object
   Set Challenger = CreateObject("Sheriff.Challenger")
   'Initialize the Challenger with secret codes
   Challenger.Secret1 = "0763198532076621"
   Challenger.Secret2 = "1854207641987532"
   Challenger.Secret3 = "2482159326044927"
   Challenger.Secret4 = "3739062895179618"

   hr = Challenger.CreateChallenge(ChallengingData, ChallengedData)

End Sub

Please note that the Secret Codes used in the demo are for evaluation. You need to replace them with your own Secret Codes when you have purchased a Sheriff Serial Number.

And that’s all, your application is now protected!


 Automatic Mode Event Handlers

Now your application is protected by Sheriff under its Automatic Mode, you might want to add some more features to your protection. Basically this adding some event handles to handle the events that might be fired up by Sheriff.

  1. The first event you might want to handle is OnTooManyUsers. This event is fired up by Sheriff when the concurrent user limit defined in the licence has been reached while a user is trying to login. In your event handler, you might firstly want to display a message box to say that there are too many users currently using the licence and then either exit the application or let the application continue to run for that user but only in demo mode with limited features.

    2. The event handler might look like this:

    Private Sub Sheriff1_OnTooManyUsers()
      MsgBox "There are too many users"
      'take appropriate action'
    End Sub
  2. In the event of an error, Sheriff will fire up the OnError message. This event message comes with two parameters: lErrorCode, bstrErrorMsg. lErrorCode is the error code of the problem and bstrErrorMsg is the error message.

    3. The event handler might look like this:

    Private Sub Sheriff1_OnError(ByVal lErrorCode As Long, ByVal bstrErrorMsg As String)
       MsgBox bstrErrorMsg
    End Sub
  3. If the Auto Trial is set on, Sheriff will automatically issue a trial licence (should the machine has never been licensed to run the application) ie. It is the very first time the user attempts to run the application. If a trial licence is issued successfully, Sheriff will then fire up the OnTrial message. If you wish to take any action when the trial licence is issued, such as presenting a message box to confirm that the user is now allowed to enter into the evaluation time, then you can handle OnTrail event.

    4. The event handler might look like this:

    Private Sub Sheriff1_OnTrial()
       MsgBox "You're now entering evaluation time"
       'take appropriate action'
       '...
    End Sub
  4. During the evaluation period you might want to check the usage of the licence and remind the user of the current licence status. For instance, you may check to see how many days the user is allowed to use the application and how many days are left. This task is accomplished by providing an event handler for the OnStart message. Sheriff fires up the OnStart message once the call to the CheckLicence method succeeds.

    5. The event handler might look like this:

    Private Sub Sheriff1_OnStart()
       MsgBox "OnStart"
       hr = Sheriff1.QueryLicenceInfo()
       'take appropriate actions
       '...
    End Sub
  5. If you elected not to let Sheriff automatically issue a trial licence or present its authorization dialog box when it detects that the machine has not been licensed, then Sheriff will fire up a OnProductNotAuthorized message. You need to handle this event in your code and provide your own dialog box or take whatever action that is appropriate to your requirements.

    6. The event handler might look like this:

    Private Sub Sheriff1_OnProductNotAuthorized()
       MsgBox "Product is not authorized"
       'take appropriate actions
       '...
    End Sub
  6. Finally, if you decided not to let Sheriff automatically present its renewal dialog box as soon as it detects the licence has expired, then Sheriff will fire up an OnLicenceExpired message. You need to handle this event in your code and provide your own dialog box or take whatever action that is appropriate to your requirements.

    7. The event handler might look like this:

    Private Sub Sheriff1_OnLicenceExpired()
       MsgBox "Licence Expired"
       'take appropriate action'
       '...
    End Sub


 Advanced Mode

If you call the CheckLicence method, you put Sheriff into "Automatic Mode". Under the Automatic Mode, Sheriff checks the status of the current licence and fire up appropriate messages whenever it is needs to. The application only needs to handle these message appropriately. Automatic Mode is easy to understand and implement and most of developers will want to use the Automatic Mode. However, some applications might have a protection requirement that is more complicated that that provided by Automatic Mode. These applications may need to control the time a licence should be issued and perhaps to perform some complicated tasks that make using Automatic Mode unsuitable. If this is the case for your application, then the Advanced Mode is what you need.

The key difference between the Automatic Mode and Advanced Mode lies in the call to the CheckLicence method: Automatic Mode calls this method to start, whereas Advanced Mode never calls this method.

Another difference you might notice is that Sheriff handles the heartbeating automatically under Automatic Mode. In fact, Sheriff does fire up an OnHeartbeat message on every heartbeat. Usually, there is no need for the application to handle this message. On the Advanced Mode, however, the application has to handle the heartbeating. This is usually done by inserting a timer control and call the UpdateLicence method on the event of timer message.

Should you decide to use the Advanced Mode, you may want to read the topic "Developer’s Guide" for a complete knowledge of how it works and what procedures needed to follow. Although some of the methods are slightly different in name, the general principle is the same. A complete list of methods, events and properties are listed in the topic "Technical Reference". A demo project in VB 6.0 is also provided.


 Technical Reference

This reference lists all of the properties, methods and events of the Sheriff ActiveX Control.

Properties

The properties are listed in their categories, namely Company Info, Product Info, Trial License and Miscellaneous.

Company Info

All of the properties in this category are for providing information about your company. This information is used and displayed on the licensing dialog box if Auto Authorize or/and Auto Renew options are set on.

  1. CompanyName
  2. Address1
  3. Address2
  4. City
  5. Country
  6. Post Code
  7. Phone
  8. Fax
  9. Email
  10. WebSite

These properties are self-explanatory.

Product Info
  1. ProductName

    2. The name of your product.

  2. ProductID

    3. The ID of your product. Sheriff ActiveX Control comes with a pre-defined evaluation product ID that can be used for your evaluation and testing. You need to obtain a product ID of your own if you decide to use Sheriff in your commercially released product.

  3. AutoTrial

    4. Instructs Sheriff ActiveX control to automatically issue a trial licence.

  4. AutoAuthorize

    5. Instructs Sheriff ActiveX control to automatically authorize a licence with a built-in licensing dialog box. Your company information will be displayed in the licensing dialog box as well as the user reference code, licence key and publisher’s data.

  5. AutoRenew

    6. Instructs Sheriff ActiveX control to automatically renew a licence with a built-in licensing dialog box. Your company information will be displayed in the licensing dialog box as well as the user reference code, licence key and publisher’s data.

  6. HeartbeatTime

    7. Defines the interval of heartbeating time. Heartbeating is a way of notifying Sheriff that the application is alive and, in the case of unit metering, updating Sheriff of the usage of the unit meter.

  7. ReclaimTime

    8. Defines when Sheriff can reclaim a dead licence. A dead licence is the licence that was requested and held by an application but its heartbeat has ceased for a period of time that is longer than the HeartbeatTime.

Licence Info
  1. Type

    2. Type of the licence. Its values are explained in the SDK and can be found in the slsapi.bas. With ActiveX control you don't need to manipulated it directly, instead you will want to set the following properties such as IsReusableKey, IsTimeMeter etc which are a breakdown of the possible values of the licence type.

  2. IsReusableKey

    3. A reusable licence key makes the licence reusable on the same PC given that the hardware components do not change. A reusable licence key allows the user to recover his/her licence in the event that the licence is damaged or lost by accident. Typically you would only want to issue a reusable licence key with time or expiration restrictions.

  3. IsReusableRef

    4. Sets the user reference code to be reusable.

  4. IsExportable

    5. Defines whether or not a licence is exportable.

  5. IsStandalone

    6. Defines whether a licence is a standalone or network licence. A standalone licence is locked to the machine from which the licence is authorised and therefore is not sharable with other users.

  6. IsTimeMeter

    7. Define whether the licence is limited by a number of days that is defined by the Meter property.

  7. IsUnitMeter

    8. Define whether the licence is limited by a number of units that is defined by the Meter property.

  8. IsSetExpiration

    9. Defines whether the licence will expire by the predefined date that is set by the EndDate property.

  9. IsSetCoUsers

    10. Define the maximum concurrent users that can use the licence simultaneously.

  10. Meter

    11. Defines the maximum number of days if the IsTimeMeter is set, or the maximum number of units if the IsUnitMeter is set.

  11. EndDate

    12. Defines the expiration date if the IsSetExpiration is set.

  12. CoUsers

    13. Defines the maximum number of concurrent users if the IsSetCoUsers is set.

  13. AccessKey

    14. Defines the feature access level.

  14. State

    15. Returns the current state of the licence when QueryLicenceInfo method is called. Please refer to the API Reference for its description.

  15. StartDate

    16. Returns the start date or purchase date of the licence when QueryLicenceInfo method is called.

  16. MeterUsage

    17. Returns the usage of the meter when QueryLicenceInfo method is called.

  17. ActiveUsers

    18. Returns the number of active users when QueryLicenceInfo method is called.

  18. Publisher Data

Sets or returns the publisher’s data.

Miscellaneous
  1. LicencePath

    2. Defines the location of the licence files. If LicencePath is not given, Sheriff ActiveX control will create and locate licence files in the directory where it is installed.

  2. UserName

    3. Provides the name of the user who is running the application.

Methods

Apart from those methods that return boolean, all of other methods return an error code that indicates success or failure. A list of error codes can be found in the SLSAPI.bas and are explained in the API reference (see on-line help: Sheriff.chm).

  1. CheckLicence() As long

    2. Call this method to check licence and run Sheriff ActiveX control in Automatic Mode.

  2. GetReference(byref ReferenceCode As String)

    3. To get the user’s reference code.

  3. SetLicence(ReferenceCode As String, LicenceKey As String)

    4. To issue a licence with the user’s reference code and its licence key.

  4. RequestLicence(byref AccessKey As long) As long

    5. To request a valid licence to run the application. AccessKey returns the feature access level defined by the licence.

  5. UpdateLicence() As long

    6. To update licence on heartbeat.

  6. ReleaseLicence() As long

    7. To release licence as soon as the application does not need the licence.

  7. RequestLicenceUnits(UnitsReserved As long, byref UnitsGranted as long,

    8. byref AccessKey as Long) As long

    To request a valid licence and reserve a number of units to run the application. AccessKey returns the feature access level defined by the licence.

  8. UpdateLicenceUnits(UnitsReserved As long, UnitsConsumed As long,

    9. byref UnitsGranted As long) As long

    To update licence on heartbeat with the number of units consumed. In addition, to modify the number of units the application wants to reserve.

  9. ReleaseLicenceUnits(UnitsConsumed As long) As long

    10. To release licence when the number units has been consumed in the session.

  10. IsExportableLicence() As Boolean

  11. IsStandaloneLicence() As Boolean

  12. IsReusableLicence() As Boolean

  13. IsReusableReference() As Boolean

  14. IsLicenceValid() As Boolean

  15. IsProductLicensed() As Boolean

  16. IsProductRegistered() As Boolean

  17. IsProductInstalled() As Boolean

  18. IssueLicence(bstrChallengeData As String) As Long

    19. To issue a licence. The licence features should be set via the licence properties such as Meter, EndData etc. You need to support challenge to be able to issue a licence. Please refer to the Advanced demo for codes of how to make a challenge.

    IssueLicence will also set the publisher’s data.

  19. ImportLicence(bstrReferenceCode As String, bstrImportKey As String) As Long

    20. To Import a licence.

  20. ExportLicence(bstrReferenceCode String,byref bstrExportKey As String) As Long

    21. To export a licence.

  21. RemoveLicence(bstrChallengeData As String ,Options As Long) As Long

    22. To remove a licence. The options are explained in the API reference. You need to support challenge to be able to remove a licence. Please refer to the Advanced demo for codes of how to make a challenge.

  22. TerminateLicence(byref bstrTerminateCode As String) As Long

    23. To terminate a licence.

  23. QueryLicenceInfo() As Long

    24. To query current licence information. Licence information is returned in the licence and licence info properties, such as Type, State, EndDate, StartDate etc.

    QueryLicenceInfo will also return the publisher’s data.

  24. GetLastError(byref LastError As long) As Long

    25. Returns last error code.

  25. GetLastErrorMessage(byref ErrorMessage As String)

    26. Returns last error message

  26. GetErrorMessage(ErrorCode As Long ,byref ErrorMessage As String)

    27. To retrieve the error message given an error code returned by any other method.

  27. GetChallengeData(byref bstrChallengeData As String) As Long

    28. Used to make a challenge when calling IssueLicence or RemoveLicence.

  28. GetStatusCode(byref bstrStatusCode As String, byref ErrorCode As Long) As Long

    29. To retrieve the current status code of the licence.

Events

Sheriff only fires up the following event messages when running in the Automatic Mode.

  1. OnTrial
  2. OnStart
  3. OnChallenge
  4. OnHeartbeat
  5. OnError
  6. OnProductNotLicensed
  7. OnProductNotAuthorized
  8. OnLicenceExpired
  9. OnTooManyUsers

Please refer to the previous sections for a description of these messages.


Notes

Overview

The Licence Key Generator is used by software vendors to create keys for their customers, while the Administrator enables end users to manage their licence keys. Note that the full functionality of these applications is replicated in the Sheriff API (via SlsApi and SlsApiEx) enabling a very high degree of customisation. Consequently you can choose whether or not to distribute the Administrator to your end users as a stand-alone application or to integrate some or all of its functionality within your own program.

The Administrator On-line Help

The Sheriff Administrator on-line help is provided both as a topic in the Sheriff on-line help that you are currently viewing and also as a stand-alone application (SlsAdmin.chm). The HTML source documents that make up the Administrator Help are provided in the folder Apps\SlsAdmin Docs.

If you want to distribute the Sheriff Administrator On-line Help please note:

  1. The Compiled Help File

    MS HTML Help is a single (.chm) file HTML help system, using its own Microsoft HTML Help viewer (hh.exe), currently available for Windows only and using MS Internet Explorer 3.02+. Therefore your users need to have Microsoft Internet Explorer 3.02 or above and the HTML Help viewer set up on their computers.

  2. The Viewer

    The MS HTML Help viewer is included in Windows 98 and is widely available but it is possible that some of your users will not have it. This means that you may need to distribute the viewer with your product.

    You can redistribute the HTML Help Viewer components as needed by redistributing the HTML Help Viewer Installation and Update package (Hhupd.exe). The package consists of a self-extracting executable program that will set up the Help Viewer on a user's computer or update an existing setup of the Help Viewer. Hhupd.exe is available in 28 languages, for both x86 and alpha platforms. Note that Hhupd.exe will not run on a Windows NT system unless you have administrator privileges.

    The viewer can be downloaded from http://msdn.microsoft.com/workshop/author/htmlhelp/distrib.asp

  3. MS Internet Explorer

    It is not required that Internet Explorer be used as the system's default browser, or that the Internet Explorer icon be visible on the user's desktop.

  4. HTML Source Documents

    You may want to customise the provided HTML Help source documents and create your own HTML Help for your users. This can be done either by purchasing a proprietary HTML Help authoring package by using the free MS HTML Help Workshop 1.2.1, which is downloadable (4MB) free of charge from Microsoft at http://msdn.microsoft.com/workshop/author/htmlhelp/download.asp

Password Protection

Both the Licence Generator and Administrator feature the option of password protection but please note that the security provided is very basic.


Demo Application

The demo is a small sample application to show how a program may be licensed.

  • You will need to copy SlsApi.dll from the API folder into the Demo App folder, or to a folder in the system path.
  • Run SlsDemo and, when prompted for a licence key, generate one with the Sheriff Licence Generator (SlsGen) located in the Apps folder.

The Visual C++ source code can be found in the Demo Source/Vc folder, which also contains projects for VB, VFP and Delphi.


Sheriff Product ID & Secret Codes Generator

Serial Number

Every Sheriff-protected product requires a unique Product ID and Secret Codes, which are generated from the Serial Number issued to you at the time of purchasing Sheriff. To generate your Product ID and Secret Codes enter the Serial Number in the Product SN box then click on Generate.

The Product ID is used to identify your product to Sheriff; you must register your Product ID in the Sheriff Licence Generator's Registry before you can issue licence keys to your users.

Secret Codes prevent third parties from generating licence keys for your product - even if they have access to the Sheriff Licence Generator. As an additional precaution the Secret Codes are also available in an encrypted format, designed to deter hacking. Whether you include the numeric or encrypted Secret Codes in your product is up to you.

Evaluation Product ID & Secret Codes

If you have not purchased a Serial Number you can use the evaluation Product ID and Secret Codes to evaluate Sheriff.


 Overview

Introduction

The Sheriff Software Development kit is used by software publishers to protect their products from illegal use by ensuring that the products are only run on machines for which they are licensed. In order to run a Sheriff-protected product for the first time an end user needs to obtain a unique licence key, which is generated by the publisher using the Sheriff Licence Generator (SlsGen.exe).

A licence key is stored in a licence file on the customer's hardware, which must be present in order for the publisher's software application to run. Because the licence file is bound to the user's hardware, it is not possible to run the application illegally.

To generate licence keys, a product will need to be registered using the Sheriff Licence Generator. Registering a product requires a Product ID and Secret Codes , which are embedded in the product by a software developer.

Obtaining a Product ID & Secret Codes

Purchase

Purchasers of Sheriff receive a unique Serial Number with which to generate their Product ID and Secret Codes (each Serial Number can generate only one Product ID and Secret Codes, so if you want to protect more than one product you will need to purchase a Serial Number for each additional product). These will protect an unlimited number of copies of your product but if you wish to protect more than one product you should purchase additional Serial Numbers. To generate a unique Product ID and Secret Codes enter your Serial Number in the Sheriff Product ID & Secret Codes Generator (SlsPsn.exe).

Evaluate

If you wish to evaluate Sheriff you can use the evaluation Product ID and Secret Codes (shown in this on-line help) to register your product. This way you can produce an unlimited number of 30-day evaluation licence keys to fully test Sheriff prior to purchase.

Register your Product

When you have a obtained a Product ID & Secret Codes you should register your product in the Sheriff Licence Generator's Registry.


Registering a Product

To generate licence keys for your product you will need to register the product in the Licence Generator by entering a Product ID and Secret Codes (if you have not yet purchased a Product ID & Secret Codes, use the evaluation versions - see topic "Evaluation Product ID"):

  • Select File from the drop-down menu, then Register Product. The Register a New Product dialog box appears.

  • Type in the name of your product and type or paste the Product ID and the four lines of Plain (numeric) Secret Codes.

  • Click OK (you can review the product details any time by selecting the Properties button).

  • When your product has been registered you can start generating licence keys.


Evaluation Product ID

Evaluation Product ID & Secret Codes

These are provided for evaluation purposes only and permit the generation of an unlimited number of 30-day licence keys. To fully protect your product you will need to purchase a unique Serial Number.

Note that use of the encrypted Secret Codes is optional - refer to the Demo to see how the encrypted secret codes can be used in your application. You should enter the plain Secret Codes in the Sheriff Licence Generator.

Product ID

9758-3050-1918-9292-6466

Plain Secret Codes

Secret Code 1: 0763-1985-3207-6621

Secret Code 2: 1854-2076-4198-7532

Secret Code 3: 2482-1593-2604-4927

Secret Code 4: 3739-0628-9517-9618

Encrypted Secret Codes

SLS_SECRET g_arySecrets[]=

{

{0x76,0x3E,0x6D,0x36,0x14,0x14,0x6D,0xB8,0x1D,0xCA,0xF3,0xD5,0x34,0x2D,0x08,0xBC,0x14,0x31},

{0x00,0xB7,0x17,0x00,0x43,0xFC,0xC0,0x7F,0x8F,0xA2,0x22,0xD2,0x1B,0x62,0xB3,0xDE,0x95,0x3F},

{0xAC,0x2E,0x39,0x6F,0x45,0xD5,0x41,0x11,0x43,0x41,0x2B,0x75,0x9C,0xB2,0x67,0x6E,0x14,0x02},

{0x79,0x52,0x9A,0x49,0x97,0x8B,0x1C,0x15,0x64,0xB7,0xBE,0x6C,0x7F,0x18,0xC3,0x4E,0x78,0x87},

};


Licensing a Product

Licensing a product is a two step procedure:

  1. The user generates a Reference Code for the publisher using the Sheriff Administrator (SlsAdmin.exe)

  2. The publisher issues the user with a Licence Key using the Licence Key Generator (SlsGen.exe)

The user (U) must generate a Reference Code on the hardware for which the product is to be licensed. The Reference Code may be generated as part of the installation process or separately using the Sheriff Administrator. The steps shown below assume the user is using the Administrator but if this is not the case simply omit this stage.

Administrator

  • U opens the Product Registry by selecting Licence | Registry (or by clicking the Registry button on the toolbar).

  • The Registry displays details of the registered products, including Product ID and Licence Path.
  • U selects the product and clicks on the License button and the License Product dialog box displays the Reference Code.
  • U informs the publisher of the Reference Code.

  • (Optional) U informs the publisher of the Status Code.

Licence Key Generator

  • P enters the user's name.
  • P selects the appropriate product from the drop-down list.
  • P enters U's Reference Code.
  • P defines the licence policy by enabling the licence features and selecting the options.
  • P clicks on the Generate button to produce a Licence Key for the User.
  • U enters the Licence Key in the Licence Product dialog box and clicks Save. The product is now licensed.


The Licence Policy

Prior to issuing a user with a licence key you must create the licence policy. The licence policy defines exactly how the user will be able to operate your Sheriff-protected application, for example whether use of the application will be restricted to a particular machine or whether the licence will expire after a certain number days. Details of every licence you issue are saved to a log file (SlsGen.log), to which you can append your own comments.

Renewing a licence overwrites the existing policy. For example, if you want to extend a user's licence from thirty days to sixty you must take into account the number of days already used. In this example, if the user had already used up fifteen days, you would issue a licence key for forty-five days. You can check the number of days that have been consumed by using the Verify Status feature (see topic "Verify Status").

Licence - Time Meter

Software runs for a specified number of days (E.g. 21 days).

Licence - Unit Meter

Each chargeable event is known as a 'unit' (E.g. an execution of the software, viewing/printing a document, or any specified period of time).

Note that any additional days/units you will overwrite those already issued. E.g. if you first issue a licence key for 180 days and during this time the user requests that the licence be extended to a total period of one year, you must take into account the units already consumed when issuing the new licence. This is not a problem because you can verify the user's Status Code prior to issuing the new licence key.

Licence - Expiry Date

The licence will expire on the selected date.

Licence - Concurrent User Limit

Limits the maximum number of concurrent network users. If this box is not checked then the number of concurrent users will be unlimited. If you check the box and the limit is set to "1" you have the option of restricting usage to a single machine i.e. the licence will be tied to the machine on which it is installed (see Standalone Licence Key below).

Licence - Feature Access Key

Software can be licensed as shareware, demo software or buy-as-you-need.

Options - Reusable Key

The user should keep a record of the licence key number. Provided you enable the 'Reusable Key' option when defining the licence policy, the user will be able to regenerate the key on the original hardware using the Licence Administrator (this can be done if, for example, the licence file is accidentally deleted). The 'Reusable Key' option can only be enabled if the key is to last indefinitely (not metered or set to expire). Note that even a reusable key cannot be restored if the user's hard disk has been reformatted.

Options - Reusable Reference Code

This option is only available when Expiry Date metering has been selected. It is used when you want to be able to extend the date on which the licence will expire without first contacting the user for a new Reference Code. In this way you can at any time extend the period for which your application will run simply by generating a new licence key for the user.

Options - Disable Export

You can disable the user's ability to export a licence key to another machine, so locking the licence to one machine only. NB. For security reasons export must be disabled if you are issuing a Reusable Key (the Disable Export option is automatically invoked when you issue a Reusable Key).

Options - Standalone Licence Key

When the Concurrent User Limit is set to "1", checking the Standalone Licence Key box ensures that the protected application can only execute on the machine on which it is installed i.e. the application is not available over a network and the licence file must reside on the same machine as the application.

Comments

You can add any comments to the log file (SlsGen.log), an ASCII text file which automatically keeps track of all transactions in the Licence Generator.

Publisher Data for User (optional)

If a publisher feels that the Sheriff Licence Key does not provide enough features, the Licence Key can be supplemented by Publisher Data. Publisher Data is saved with the Licence Key and is in effect an an extension to the Feature Access Key facility. However, unlike the Feature Access Key, Publisher Data can be up to 32 bytes long and is entered by the user at the time of entering the Licence Key. The Publisher Data may be saved or retrieved by using the appropriate Sheriff API functions.


Verify Status

Use Verify Status to display the features of a user's existing licence prior to issuing a new key. This is particularly important if you want to renew a licence that has not already expired as the new licence policy will overwrite the existing one. In such cases you will need to take into account any days/units etc. that remain on the old policy.

The user must run the Sheriff Administrator (SlsAdmin.exe), the publisher must run the Licence Key Generator (SlsGen.exe).

Sheriff Administrator

  • The user (U) selects the Registry and the appropriate product from the combo box.
  • U clicks on License and then on 'yes' in Confirm Buy dialog box.
  • The status code of the existing licence is displayed.

Licence Key Generator

  • The publisher (P) clicks on the key in the top left hand corner and chooses Verify Status Code from the drop down menu.
  • P enters U's status code (and optionally the user's name and any comments in the Comments box) and clicks Verify.
  • The licence features are displayed and details will be appended to the Licence Generator Log file (SlsGen.log).


Terminating a Licence

Overview

Generally a user's licence will terminate automatically, for example if unit metering has been enabled and all the units have been consumed, however there may be instances where it is necessary to terminate a licence manually.

For example, a user may wish to change a hardware component but be unable to use the 'import' facility because there is no other system available (for more about 'import' see the Licence Administrator help). In such cases the user requests the publisher to generate a new licence key but before doing this the publisher must verify that the original licence has been terminated.

The user (U) terminates a licence using the 'Terminate' option in the Sheriff Licence Administrator (SlsAdmin.exe). Terminating a licence generates a termination code that can be verified by the publisher (P) using the Verify Termination Code facility in the Sheriff Licence Key Generator.

Administrator

  • U clicks the Licence menu and selects Terminate.
  • The Terminate Product dialog box displays the currently registered products, U selects a product to terminate and clicks on the Terminate button.
  • When U has confirmed that the product should be terminated, the termination code is displayed.

Licence Key Generator

  • P runs the Licence Key Generator, clicks the key icon at top left and selects Verify Termination Code on the drop down menu.
  • P enters U's Termination Code in the dialog box - it is not possible to complete the entry of an invalid code.
  • When the code is successfully entered P adds any comments in the Comments box.
  • P clicks on the Verify button to display the licence properties.
  • Details of the licence termination are appended to the Licence Key Generator Log file (SlsGen.log).


Removing a Product

Removing a Registered Product

The Remove Product facility enables you to completely remove a Sheriff-protected product, for example where you want to reinstall the product again from scratch on your development machine.

Normally this option is not made available to the end user - use Terminate instead. By using the Terminate procedure you ensure that a product is removed from the user's machine without by-passing the Sheriff protection, whereas Remove completely undoes the installation. The procedure is password protected.

Administrator

  • Click on Licence | Remove.
  • In the Remove Products dialog box select the product and click Remove.
  • A Reference is displayed.

Licence Key Generator

  • Click the key in the top left hand corner.
  • Select Generate Remove Password.
  • Enter the Reference Code and click on Generate to generate a password.

Administrator

  • Enter the password and click on OK. The product is now removed.


Introduction

Sheriff is used by software publishers to protect their products from illegal use by ensuring that they can run only on machines for which they are licensed. In order to run a Sheriff-protected product for the first time you must obtain a unique licence key from the publisher. Normally this process takes place when a product is installed, although it can be done manually using the Sheriff Administrator.

A licence key is stored in a licence file on your hardware; because the licence file is bound to the hardware, it is not possible to run the publisher's application illegally.

To obtain your licence key you must supply the software provider with a Reference Code, normally displayed at the time of installation. The 24-digit Reference Code incorporates a unique digital fingerprint of the computer on which it was generated and the licence key granted by the software provider is also unique to that computer. If a Sheriff-protected software product is copied to another computer it will fail to run unless (a) the software provider issues a new licence or (b) an existing licence is imported from another computer or (c) the software is being run on a network and there are spare licences available on the server.

In order to run, a Sheriff-protected product must be both registered and licensed on the user's computer. Normally both of these operations are performed on installation but it is also possible to register and/or license a product with the Sheriff Administrator. For further information see the topic Registering & Licensing Overview.


Administrator Overview

With the Administrator you can:

  • Register and/or license Sheriff-protected products.
  • Monitor licence usage (E.g. by networked users).
  • Manage networked users (Eg. suspend a user's access).
  • Maintain portable licences (using the import/export facility).
  • Regenerate a licence file that has been deleted or corrupted.
  • Terminate a licence manually and provide verification to the publisher
  • Remove a licensed product (used by software developers for debugging)

All Sheriff-protected products can be managed from a single Administrator, even those from different software publishers.


Registering & Licensing Overview

Registering a Product

The licence policy contains all the licensing information for a Sheriff-protected product and is stored in a special licence file. This can be located in a folder that is named with the Product ID of the Sheriff-protected product.

To 'read' the licence policy a product must know where to locate the licence file; this information is stored in the Sheriff Registry.

The Sheriff Registry is normally automatically updated when a Sheriff-protected product is installed but to provide additional flexibility, particularly in a networked environment where a single licence file is shared between many machines, it is possible to manually edit the information in the Registry. For further details see the topic Registering a Product.

Licensing a Product

Licensing a product involves obtaining a licence key from the product's publisher. The licence key is used to generate the licence file referred to above. Normally this is part of the installation process (i.e. when a product is installed for the first time, you are shown a Reference Code from which the publisher will generate your licence key) but it is also possible to license a product manually. For further details see the topic Licensing a Product.


Registering a Product

Click the Registry button on the toolbar to open the Sheriff Registry.

The Product Name box provides a drop-down listing of all your registered products. Most products are self-registering (i.e.automatically registered on installation) however it is also possible to register a product manually by typing in the name of the product, the Product ID and selecting a path for the licence file. Normally this is only necessary for networked products or when using the Import procedure to import a licence from another machine.


Licensing a Product

Licensing New Products

As mentioned, Sheriff-protected products are normally automatically licensed on installation.

To manually license a product, click on License and a License Product dialog box displays your Reference Code. Inform the software publisher of the Reference Code and you will be issued with a 40-digit licence key. Make a note of the licence key number, enter it in the License box and click on Save to enable the licence. The software program will now run normally. It can be important that you make a note of the licence key (see below).

Regenerating a Licence File with a Reusable Licence Key

Provided your licence is not exportable or set to expire (E.g. on a particular date or after a set number of days) it is possible that your publisher has issued you with a 'Reusable' licence key. This means that you will be able to regenerate the licence file on the same machine* in the event that it is overwritten or damaged. Enter the licence key number into the Licence Product dialog box and click Save to regenerate the licence file.

* Provided the hard disk has not been reformatted.


Importing/Exporting a Licence

Overview

The import facility enables you to operate a Sheriff-protected product on a machine for which you do not have a licence.

To understand this topic it is important to appreciate the difference between the source machine and the target machine, since different rules apply to each. The source is the machine on which the licence was originally registered i.e. the machine for which the publisher issued the original licence key. The target is a machine to which you export a licence from the source machine.

To run a Sheriff-protected product on a target you may import a licence from the source provided that (a) the software publisher enabled this facility when defining the licence policy and (b) you adhere to the operational rules set out below.

You can import/export both standalone and network licences. All import/export activity is recorded in the log file (SlsAdmin.log).

Operational Rules

  1. The product must be registered and licensed on the source machine and also registered on the target machine before you can import the licence.

  2. You can define the features of the exported licence, provided these remain within the terms of the licence policy.

  3. When either the users or units have been fully exported the application cannot execute on the source until the licence is imported back from the target.. For example, you have a licence with two users and ten units on the source and you export one user and ten units to the target; what remains on the source is one user with zero units - meaning that the user will be unable to run the application on the source as there are no available units.

  4. A licence can only be imported either to a machine that does not already have a valid licence or to the source machine.

  5. If the licence on the source is modified after the exporting, then the exported licence cannot be imported back from the target - Sheriff sees a modified licence as a different licence.

  6. A licence can only automatically restore on the source machine - there is no automatic restoration on the the target machine.

Exporting Different Types of Licence

What happens to a licence when it is exported depends on the licence policy (i.e. on the licence's attributes, such as the type of metering in force and number of concurrent users allowed), as set out in the table below.

Concurrent Users | The number of concurrent users on the source machine will be reduced by the number exported until the exported licence expires or is imported back to the source machine.
Time Limited (Metering / Expiry Date) | As soon as an exported time-limited licence expires, the source licence will be automatically reinstated. For example, you can set the exported licence to expire after seven days and when it does the licence is automatically restored on the source machine (a licence cannot automatically restore except on the source machine ).
Unit Metering | It is not possible to automatically reinstate a unit metered licence. To recover the unconsumed units in the exported licence, the user has to manually import the licence back to the source machine.

Procedure

Target
  1. Register the product you wish to use by clicking the Registry button on the toolbar to open the Sheriff Registry (proceed to 1(b) if the product is already registered). Type in the name of the product, the Product ID and select a path for the licence file. Close the Registry.

  2. Import the product by clicking the Import button - the Import Product dialog box displays. Select the product you want to import, then click the import button - an Import Licence dialog box displays a Reference Code.
Source

  1. Click the Export button and the Exporting Licence dialog box is displayed.

  2. Select the product to be exported and click the Export button. The Export dialog box is displayed.

  3. Enter the Reference Code referred to above and define the Licence Policy by selecting the appropriate features (E.g. Expiry Date). Note that the available features will depend upon the attributes of the policy. Click on Generate and a licence key is displayed.
Target

  1. Enter the licence key into the Import Licence dialog box.

  2. Click on Import and the product is enabled.


Terminating/Removing a Licence

Generally licences terminate automatically, for example if unit metering has been enabled and all the units are consumed, however there may be instances where it is necessary to terminate a licence manually.

For example, you may wish to change a hardware component but be unable to use the 'import' facility (see previous topic) because there is no other system available. In such cases you must request the publisher to generate a new Licence Key for your software but before doing this the publisher must verify that the original licence has been terminated.

Procedure for Terminating a Licence

  • Click the Licence menu and select Terminate.

  • The Terminate Product dialog box displays the currently registered products. Select a product to terminate and click on the Terminate button.

  • When you have confirmed that the product should be terminated, the Termination Code is displayed. Make a note of this so that it can be verified by the publisher. When the product is re- installed the publisher will issue a new Licence Key.

Removing a Licence

The licence removal facility is normally only used by software developers and is documented in the Sheriff Licence Key Generator on-line help.


Networking Sheriff

Networking: The Basics

To provide network access to a Sheriff-protected product you need to ensure that the licence file is in a shared location - either a mapped drive or else a drive that is accessible via UNC.

The product has to be registered on every workstation on which it is to run. Run the Sheriff Administrator on each workstation to specify (a) the Product ID and (b) the path to the licence file. The maximum number of concurrent users cannot exceed that shown in the licence properties.

To display the licence properties open the Sheriff Registry, select the product and click on Properties.


Licence Monitoring

Networking: Licence Monitoring

You can monitor active programs and which active users have access to them.

Click on Monitor in the toolbar to display a list of software programs for which you are licensed. Select a product from those listed in the Product window and click on Monitor. The Properties for the selected product are displayed. Click on Close and the active users are displayed.

AD Monitor Current Users.gif - 3840 Bytes

In this example four users are running the Sheriff Demo program.

  • Login Date/Time shows when an active program was opened by a user.
  • Update Date/Time shows when an program was last verified (see below)

A red circle indicates that the program has been verified by the Sheriff Licence System (SLS) and granted permission to run. Usually an active program updates SLS with its current status every five minutes or so but the specified interval varies according to the program.

A red circle changing to white indicates that the program has not been verified by SLS during the specified interval and will be terminated unless the situation is corrected.


Delete an Active User

Networking: Delete an Active User

Highlight the user you wish to delete and click on the delete button. You will be prompted to confirm the deletion.

Normally you will only do this you when you have reached the limit of authorised concurrent licences and you wish to grant access to another user. For example, if you have a concurrency limit of four users and it is urgent that John is granted access, you could choose to delete Michael to make way for John.

Note that deleting a user does not prevent that user from running the software program again - it temporarily suspends the user. Also, the effect of deleting a user may be delayed, depending on how frequently the program checks its licence file.


About the SlsAPI

The Sheriff Licence System provides a management layer that can track the rights to use purchased software. You can incorporate licence enforcement and verification in your product by using the Sheriff Licence System Application Programming Interface (SLSAPI), a set of functions that provides licensing services within applications. SLSAPI-enabled applications can gain access to the SLSAPI interface through the protected dynamic-link library SLSAPI.DLL.

The SLSAPI-compliant product includes the following basic components:

  • An SLSAPI-enabled desktop application
  • The dynamic-link library SLSAPI.DLL
  • An Sheriff licence file that serves digital licence certificates

The SLSAPI functions are as follows:

SLS_Register | Registers licence system in the user’s PC
SLS_Request | Requests that the licence system grants the licensing resources so the calling application can execute.
SLS_Update | Updates the synchronisation between the licensed application and the licence system.
SLS_Release | Requests that the licence system release the licensing resources associated with a specific licence context
SLS_License | Issues licensing policy programmatically
SLS_GetReference | Returns licence reference code
SLS_SetLicence | Issues licence with licence key
SLS_QueryLicenceInfo | Returns information about licence policy and licence usage
SLS_CreateChallenge | Creates Challenge
SLS_VerifyChallenge | Verifies Challenge
SLS_GetErrorMessage | Returns the message string associated with a licensing service function status code.
SLS_IsProductInstalled | Checks if the specified product has been installed on the machine
SLS_SetOptions | Sets various options such as reclaim times
SLS_Terminate | Terminates the specified licence
SLS_GetStatusCode | Get current licence status
SLS_ExportLicence | Export licence
SLS_ImportLicence | Import licence


Licence Security

Sheriff is the most secure software-based system available. If you incorporate the Sheriff Licence System Application Programming Interface (SLSAPI) functions in your application, you can deter licence system tampering and reveal when tampering occurs.

The security model employed by Sheriff aims to stop an intruder’s attack in all areas. The model comprises of three components: encrypted licence key, encrypted licence file and encrypted Application-SLSAPI communication channel.

Encrypted Application-SLSAPI communication channel is accomplished by including a challenge/response protocol in the calls to the SLSAPI functions. It provides a very reliable way for both the licence system and the application to verify that the other is a legitimate party. It also provides a reliable encryption system to prevent the communication parameter between the application and the API from being modified en-route.

The SLSAPI functions use the MD5 Message-Digest Algorithm to implement the challenge/response protocol. This algorithm does not require patented cryptographic techniques. Knowledge of the algorithm neither compromises the secrets the application passes through it nor the level of security the SLSAPI offers.


Licensing Policy

With Sheriff you can combine the following features in your licensing policy:

  1. Concurrency
  2. Expiration
  3. Day Metering
  4. Unit Metering
  5. Feature Access Control

Concurrency Limiting

This implementation limits the maximum number of concurrent users to that permitted by the licence agreement (EULA).

Licence Metering

Sheriff provides two types of metering:

  1. Day Metering enables the software to run to a specified date (E.g. until 31/8/97) or for a specified number of days (E.g. 21 days).
  2. Unit Metering provides a flexible method for the software publisher to determine which events will be chargeable. Each chargeable event is known as a ‘unit’ (E.g. an execution of the software, viewing/printing a document, or any specified period of time). So the publisher might permit the software to be executed ten times only, this would be the equivalent of providing ten metered units.

Feature Contro l

Software publishers can distribute full versions of their software, but limit end users’ access to software features. End users can then buy what they need. Using ‘feature control’, software publishers can license their software as shareware, demo software or buy-as-you-need.


Licensing Strategies

You can customise your application to respond to the situation when a valid licence is unavailable.

The following are examples of licensing strategies:

Demonstration mode. Use the SLSAPI functions to obtain authorisation from the licence system for your application to run. If there is no licence or licence system, the software can display a warning message but continue to run in the demonstration mode.

Authorisation desired. Use the SLSAPI functions to obtain authorisation from the licence system for your application to run. If there is no licence or licence system, the software can display a warning message but continue to run.

Authorisation required. Use the SLSAPI functions to obtain authorisation from the licence system for your application to run. If no valid licence is available, the software will not run.

SlsDemo.exe demonstrates how to implement these basic licensing strategies.


How to Incorporate the SlsAPI

How to Incorporate the SLSAPI in an Application

This section provides an example of how to incorporate the Sheriff Licence System Application Programming Interface (SLSAPI) functions in your application, with and without challenge protocol.

Before you begin coding your application, you will need to obtain your Product ID and Secret Codes, either by purchasing a Serial Number or using the evaluation versions. You also need the Sheriff SDK which includes the dynamic link library SLSAPI.DLL and source code for implementing the challenge/response in your application.

To code the application

  1. Choose and implement your licensing strategy. For examples, see "Licensing Strategies".
  2. Incorporate the source codes provided in SDK to prepare the challenge.
  3. Add calls to the SLS_Request functions in your application to grant licence resources.
  4. Include periodic calls to the SLS_Update function to notify the licence system that the current licence is still being used.
  5. Incorporate code to handle errors. Call the SLS_GetErrorMessage function to return a message string that describes the error.
  6. Call SLS_Release to release licence resources before exiting from the application.


SlsAPI Data Types & Structures

SLSAPI Data Types

typedef DWORD SLS_HANDLE;

Defines the handle to the licensing context used by the licence service function calls.

SLSAPI Data Structures

Licence Date

typedef struct _SLS_DATE

{

DWORD Year,
DWORD Month,
DWORD Day;

} SLS_DATE;

The SLS_DATE defines a date structure that contains calendar year, month and day. It is part of the SLS_LICENCE structure.

Licence

typedef struct _SLS_LICENCE

typedef struct _SLS_LICENCE
{
DWORD Type; //type of licence
DWORD Meter; //for metering, e.g. Unit, Time metering
SLS_DATE EndDate; //for expiration date
DWORD CoUsers; //Concurrent users
DWORD AccessKey; //Access control key
} SLS_LICENCE;

The SLS_LICENCE defines Sheriff’s licence policy structure. It is used by SLS_License to issue licence programmatically.

Type

Specifies the type of the licence policy. It can be a combination of the following values:

//type of licence
#define SLS_TYPE_UNDEFINED 0x0000 //Undefined
#define SLS_TYPE_UNIT_METER 0x0001 //Unit Metering
#define SLS_TYPE_TIME_METER 0x0002 //Time Metering
#define SLS_TYPE_EXPIRATION 0x0004 //Expiry Control
#define SLS_TYPE_CONCURRENCY 0x0008 //Concurrency Control

#define SLS_TYPE_REUSABLE_KEY 0x0100 //Reusable key
#define SLS_TYPE_REUSABLE_REF 0x0200 //Reusable reference
#define SLS_TYPE_UNEXPORTABLE 0x0400 //Export Disabled
#define SLS_TYPE_STANALONE 0x0800 //Standalone

Meter

Used only for metering, i.e when type is either SLS_TYPE_UNIT_METER or SLS_TYPE_TIME_METER, to specify the total amount of units or total number of days allowed in the licence policy. Maximum value is 99999.

EndDate

Used only for expiry date licensing, i.e. when type is SLS_TYPE_EXPIRATION, to specify the expiration date.

CoUsers

Specifies the maximum concurrent users. Maximum value is 99999.

AccessKey

Specifies a key to access application features. A software application can offer many features and these features can be managed in many levels. The software publisher may want to license the software in levels. The AccessKey is used by software publishers to control the accessibility of features. The AccessKey is defined by software publishers and its meaning is also only interpreted by the publishers. Maximum value is 99999.

Request

typedef struct _SLS_REQUEST
{
DWORD UnitsReserved;
} SLS_REQUEST

The SLS_REQUEST is used for requesting a licence to run the application. It is used by SLS_Request. When the licensing policy requires unit metering, the data member UnitsReserved specifies the number of units to run the application; when the licensing policy does not requires unit metering, the UnitsReserved should be set to zero.

typedef struct _SLS_PERMIT
{
DWORD UnitsGranted;
DWORD AccessKey;
} SLS_PERMIT;

The SLS_PERMIT is used for receiving a licensing permit, when SLS_Request is called to request a licence to run the application, or when SLS_Update is called to update the licence status.

UnitsGranted

Returns the total number of units granted and reserved.

AccessKey

Returns the publisher-defined feature access key.

Update

typedef struct _SLS_UPDATE
{
DWORD UnitsReserved;
DWORD UnitsConsumed;
} SLS_UPDATE;

The SLS_UPDATE is used for updating licence status. It is used by SLS_Update.

UnitsReserved

Specifies the total number of units to be reserved. If no additional units are required since the initial call to the SLS_Request function or the last call to the SLS_Update function, then this parameter should be the current total returned in the SLS_PERMIT.UnitsGranted parameter. The total reserved includes the units consumed. That is, if an application requests 100 units, and then consumes 20 units, there are still 100 units reserved but only 80 available for consumption.

If additional units are required, the application must calculate a new total for UnitsReserved.

The licence system verifies that the requested number of units exist, and it may reserve those units, but these units are not consumed at this time.

This value may be smaller than the original number requested by SLS_Request to indicate that fewer units are needed than originally anticipated.

UnitsConsumed

Specifies the total number of units consumed since the initial call to the SLS_Request function. If the UnitsConsumed exceeds the number of units reserved, the error SLS_E_UNIT_EXCEEDED is returned and the remaining units are consumed.

Release

typedef struct_SLS_RELEASE
{
DWORD UnitsConsumed;
} SLS_RELEASE;

The SLS_RELEASE is used by SLS_Release to report licence usage.

UnitsConsumed

Specifies the total number of units consumed since the initial call to the SLS_Request function.

Licence Info

typedef struct _SLS_LICENCE_INFO
{
//Licence Part
DWORD Type; //type of licence
DWORD Meter; //Units or Days limit
SLS_DATE EndDate; //Expiration date
DWORD CoUsers; //Concurrent users
DWORD AccessKey; //Access control key
//Usage Part
DWORD State; //State of licence
DWORD MeterUsage; //Units used, days used
SLS_DATE StartDate; //Start date
DWORD ActiveUsers; //Number of active users
} SLS_LICENCE_INFO;

The SLS_LICENCE_INFO structure is used by SLS_QueryLicenceInfo to retrieve the licence policy and its current usage.

Type, Meter, EndDate, CoUsers, AccessKey as explained in SLS_LICENCE.

State

Returns the state of the licence being requested. Its value can be one of the following:

#define SLS_STATE_UNDEFINED 0x0000 //Licence is undefined
#define SLS_STATE_BAD 0x0001 //Licence is invalid
#define SLS_STATE_EXPIRED 0x0002 //Licence has expired
#define SLS_STATE_EXHAUSTED 0x0003 //Licence units have run out
#define SLS_STATE_OK 0x0008 //Licence is valid

MeterUsage

Specifies the total number of units or days that have been used since the licence was purchased.

StartDate

Specifies the purchase date of the licence policy

ActiveUsers

Specifies the number of active users at the time this information is being requested.

Challenge

typedef struct _SLS_CHALLENGE
{
DWORD Protocol;
DWORD Size;
SLS_CHALLDATA ChallengeData;
} SLS_CHALLENGE;

The SLS_CHALLENGE structure is used for both the challenge and the response of the SLS_License, SLS_Request and SLS_Update licence service functions. It is the main structure in the challenge/response mechanism, and it is supported by all challenge/response protocols.

Protocol

Specifies the protocol setting for licence authentication. Currently only the basic protocol SLS_BASIC_PROTOCOL is supported. If challenge is not desired, Protocol should be set to SLS_NO_PROTOCOL.

Size

Specifies the size, in bytes, of the ChallengeData (SLS_CHALLDATA) structure.

ChallengeData

Structure that contains the challenge that the application passes to the licence system and the response the licence system returns to the application.

Remarks

Use the SLS_CHALLDATA structure to pass the challenge to the licence system. The licence system also returns the challenge response in the SLS_CHALLDATA structure.

Because the SLS_CHALLDATA structure can vary depending on the protocol specified in the Protocol member, this structure must be a single contiguous entity in memory and must not exceed the number of bytes specified in the Size member. It cannot contain any pointers.

SLSAPI passes the Protocol, the Size of the SLS_CHALLDATA structure, and the actual data contained in the structure to the licence system. The licence system, in turn, casts the byte sequence into the appropriate structure based on the Protocol specified.

The constant value SLS_BASIC_PROTOCOL specifies a standard basic challenge protocol that is supported by all SLSAPI. When the Protocol specified is SLS_NO_PROTOCOL, there is no challenge and no response.

Challenge Data

typedef struct _SLS_CHALLDATA
{
DWORD SecretIndex;
DWORD Random;
SLS_MSG_DIGEST MsgDigest;
} SLS_CHALLDATA;

The SLS_CHALLDATA structure is passed in the SLS_CHALLENGE structure. The SLS_CHALLDATA structure passes the challenge from the application to the licence system, and passes the response from the licence system back to the application.

SecretIndex

Specifies the index of the secret value to be challenged. The secret index is 1-based.

Random

Specifies a random 32-bit value.

MsgDigest

Structure that contains the message digest that is computed by the MD5 Message-Digest Algorithm from RSA Data Security, Inc.

Remarks

In the basic challenge protocol, the application must choose the index of the secret to be challenged and it must generate a random number. It must then compute a message digest using the MD5 Message-Digest Algorithm. The input to the algorithm is formed by concatenating the input parameters to the function being called, the random number, the index of the secret to be challenged, and the actual secret value. The input parameters are described in the SLSAPI functions. The application then passes the algorithm output to the licence system.

The licence system authenticates the message digest and computes a new message digest consisting of the output parameters, a new random number, a new index of the secret to be challenged, the actual secret value and the returned status. This new message digest is passed back to the application, which, in turn, authenticates it. Note that the actual secret value never passes between the application and the licence system in plain text.

If the function h(x) is the algorithm that, given input x, returns the output of the MD5 Message-Digest Algorithm, then the following briefly illustrates the basic protocol.

The application passes the SLS_MSG_DIGEST structure to the licence system:

h(in + Rin + Xin + S (X) )

The licence system passes a new SLS_MSG_DIGEST to the application:

h(out + Rout + Xout + S (X) )

where:

  • in is a byte stream that encodes the input parameters
  • Rin is the random number generated by the application
  • Xin is the index of the secret to be challenged chosen by the application
  • S indicates a secret
  • S (X) is the actual secret value
  • + denotes concatenation.

Similarly:

  • out is a byte stream that encodes the output parameters
  • Rout is the random number generated by the licence system
  • Xout is the index of the secret to be challenged chosen by the licence system

This data format can be invalid if the Protocol specified in the SLS_CHALLENGE structure is not SLS_BASIC_PROTOCOL. Other protocols may define their own SLS_CHALLDATA format. Particularly if the Protocol is specified as SLS_NO_PROTOCOL then there will be challenge implemented between the application and the licence system.

Message Digest

typedef struct _SLS_MSG_DIGEST
{
char MessageDigest[16]; //binary data
} SLS_MSG_DIGEST;

The SLS_MSG_DIGEST structure is passed in the SLS_CHALLDATA structure. The MD5 Message-Digest Algorithm from RSA Data Security, Inc., computes the SLS_MSG_DIGEST structure by using the following elements as input: the input and output parameters to the LSRequest or LSUpdate licence service functions; a random number; the index of an application secret; and the actual application secret.

MessageDigest[16]

Specifies a 128-bit message digest that is the output of the MD5 Message-Digest Algorithm.

Licence Options

typedef struct _SLS_OPTIONS
{
DWORD HeartbeatTime; //heartbeat time
DWORD ReclaimTime; //reclaim time
DWORD Reserved1; //reserved, should be set to 0
DWORD Reserved2; //reserved, should be set to 0
} SLS_OPTIONS;

The SLS_OPTIONS structure is used by SLS_SetOptions to set various licence options at run time. There are two options supported in the current version, MinReclaimTime and MaxReclaimTime.

HeartbeatTime

If the user has not updated its licence status within the time specified by HeartbeatTime, then Sheriff decides that the user has become inactive and its licence is ready to be reclaimed.

ReclaimTime

If the user has not updated its licence status within the time specified by MaxReclaimTime, then Sheriff decides that the user has become inaccessible and its licence will be reclaimed immediately.

User Info

typedef struct _SLS_USER_INFO

{

char UserName[32];

DWORD UserID;

SLS_DATE_TIME LoginTime;

SLS_DATE_TIME LastUpdateTime;

} SLS_USER_INFO;

The SLS_USER_INFO structure is used by SLS_QueryUserInfo to retrieve user’s information

UserName

The name of the user as provided when call SLS_Request or SLS_RequestEx

UserID

The ID of the user as provided when call SLS_RequestEx

LoginTime

The time when SLS_Request or SLS_RequestEx is called.

LastUpdateTime

The time the last SLS_Update is called.


SlsAPI Status Codes

Status Codes

Status Code | Meaning
SLS_E_PRODUCT_CODE | Invalid Product Code (Product ID)
SLS_E_REFERENCE_CODE | Invalid Reference Code
SLS_E_MACHINE_CODE | Invalid Machine Signature
SLS_E_SYSTEM_TIME | Invalid System Time
SLS_E_OUT_OF_MEMORY | Not Enough Memory
SLS_E_OUT_OF_HANDLE | Not Enough Handles
SLS_E_CHALLENGE_ILLEGAL | Illegal Challenge
SLS_E_CHALLENGE_UNSUPPORTED | Unsupported challenge
SLS_E_ARGUMENT_INVALID | Invalid argument passed to function
SLS_E_LICENCE_HANDLE | Invalid licence handle
SLS_E_LICENCE_UNREGISTERED | Unregistered licence
SLS_E_LICENCE_UNDEFINED | Licence is undefined
SLS_E_LICENCE_EXCEEDED | Licence concurrency exceeded
SLS_E_LICENCE_EXHAUSTED | Licence meter exhausted
SLS_E_LICENCE_EXPIRED | Licence has expired
SLS_E_LICENCE_INVALID | Licence is invalid, corrupted
SLS_E_LICENCE_SUSPENDED | Licence is suspended
SLS_E_LICENCE_TERMINATED | Licence is terminated
SLS_E_LICENCE_UNAVAILABLE | Licence is unavailable
SLS_E_UNIT_UNDEFINED | Licence unit not defined
SLS_E_UNIT_EXCEEDED | Licence unit shortage (all units has been reserved)
SLS_E_BAD_SECRET | Incorrect Secret Code
SLS_E_BAD_MAC | Incorrect Message Authentication Code
SLS_E_FILE_NOT_FOUND | The file could not be located.
SLS_E_FILE_BAD_PATH | All or part of the path is invalid.
SLS_E_FILE_TOO_MANY | The permitted number of open files was exceeded.
SLS_E_FILE_ACCESS_DENIED | The file could not be accessed
SLS_E_FILE_BAD_HANDLE | There was an attempt to use an invalid file handle.
SLS_E_FILE_BAD_SEEK | There was an error trying to set the file pointer.
SLS_E_FILE_HARDIO | There was a hardware I/O error.
SLS_E_FILE_SHARING | There was a file sharing error
SLS_E_FILE_LOCKING | There was a file locking error
SLS_E_FILE_DISK_FULL | The disk is full.
SLS_E_FILE_EOF | The end of the file was reached.
SLS_E_FILE_BAD_CRC | Licence file CRC error
SLS_E_FILE_BAD_SIGNATURE | Signature error in the file
SLS_E_FILE_BAD_DATA | Data error in the file
SLS_E_PATH_INVALID | Invalid Licence Path
SLS_E_PATH_CREATE | Failed to create licence path
SLS_E_PATH_ACCESS_DENIED | Access (Read/Write) to licence path was denied
SLS_E_REG_FAILURE | Registry operation failure
SLS_E_BAD_LICENCE | Licence File been tampered
SLS_E_BAD_REGISTRY | Registry has been tampered
SLS_E_BAD_MACHINE | Machine Signature is wrong
SLS_E_OP_MACHINE_CODE | Failed to get machine code
SLS_E_OP_MACHINE_SIGN | Failed to get machine signature
SLS_E_OP_FILE_SIGN | Failed to get file signature
SLS_E_OP_DISK_SIGN | Failed to get disk signature
SLS_E_OP_TERMINATION | Failed to terminate licence
SLS_E_LICENCE_BAD_TIME | Incorrect time meter in licence
SLS_E_LICENCE_BAD_UNIT | Incorrect unit meter in licence
SLS_E_LICENCE_BAD_DATE | Incorrect expiration date in licence
SLS_E_LICENCE_BAD_COUSERS | Incorrect concurrent user limit in licence
SLS_E_LICENCE_BAD_ACCESSKEY | Incorrect access key in licence
SLS_E_LICENCE_BAD_LICKEY | Incorrect Licence key
SLS_E_IMPORT_BAD_LICKEY | Incorrect import licence key
SLS_E_IMPORT_BAD_SOURCE | Incorrect import source signature
SLS_E_REINSATTE_BAD_SOURCE | Cannot reinstate licence due to incorrect source licence
SLS_E_EXPORT_NOT_ALLOWED | Licence export not allowed
SLS_E_BAD_USER_INDEX | User Index out of range
SLS_E_UPID_SIGNATURE_REF | Machine Signatures in reference do not match
SLS_E_UMID_SIGNATURE_REF | Product Signatures in reference do not match
SLS_E_UPID_SIGNATURE_KEY | Machine Signatures in licence key do not match
SLS_E_REF_SIGNATURE_KEY | Reference Signatures in licence key do not match


SLSAPI Functions

Register Product

HRESULT SLS_Register(LPCSTR pszProductID, LPCSTR pszProductName, LPCSTR pszLicencePath)

The SLS_Register function registers a product’s licence on user’s PC.

Parameters

pszProductID

Points to a string that uniquely identifies the application’s Product ID.

pszProductName

Points to a string that identifies the application’s product name.

pszLicencePath

Points to a full path where licence files will be stored.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Remarks

The SLS_Register is the first function that needs to be called by the application before any other SLSAPI function can be called. Once a licence is registered successfully on the user’s PC, there is no need to call SLS_Register. This function is typically used by an application’s installation program to register application’s licence on the user’s PC.

Get Licence Reference

HRESULT SLS_GetReference(LPCSTR pszProductID, LPSTR pszReference)

The SLS_GetReference asks SLSAPI for the reference code associated with the product.

Parameters

pszProductID

Points to a string that uniquely identifies the application’s Product ID.

pszReference

Points to a buffer in which the Reference Code is to be placed. The minimum size of the buffer is 32 bytes.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Remarks

The application calls the SLS_GetReference to obtain the reference code of the product installed on the user’s PC. With the reference code the user can obtain the licence key from the application publisher. SLS_Reference is often called by the application that wants to programmatically issue a licence policy from the application, in which case SLS_SetLicence is called upon when the application has received the licence key from the publisher.

Set Licence

HRESULT SLS_SetLicence(LPCSTR pszProductID, LPCSTR pszLicenceKey)

The SLS_SetLicence asks the SLSAPI to authorise the product’s licence policy.

Parameters

pszProductID

Points to a string that uniquely identifies the application’s product ID.

pszLicenceKey

Points to a string which contains a licence key.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Remarks

The application calls the SLS_SetLicence to programmatically issue a licence policy with its licence key. LicenceKey is issued to the user by the publisher with the user’s reference code which is generated by a call to the SLS_GetReference.

Query Licence Info

HRESULT SLS_QueryLicenceInfo(LPCSTR pszProductID, SLS_LICENCE_INFO *pLicenceInfo)

Parameters
pszProductID
Points to a string that uniquely identifies the application’s Product ID.

pLicenceInfo
Points to a buffer to receive information about licence policy and usage.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

SLS_E_LICENCE_UNREGISTERED if the licence is not yet registered on the user’s PC.

Remarks

The SLS_QueryLicenceInfo returns an SLS_LICENCE_INFO structure data containing licence policy and its current usage. If the functions returns successfully, the state of the licence, i.e. pLicenceInfo->state should be further checked.

Get Error Message

HRESULT SLS_GetErrorMessage(HRESULT hr,LPTSTR pszErrorMessage)

The SLS_GetErrorMessage returns an error message associated by an error code.

Parameters

hr

Specifies an error status code returned from any SLSAPI function

pszErrorMessage

Points to a buffer allocated by caller to receive the error message specified in the error code hr. The minimum length of the buffer is 256 bytes.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

License

HRESULT SLS_License(LPCSTR pszProductID,SLS_LICENCE *pLicence,SLS_CHALLENGE *pChallenge)

The SLS_Licence asks SLSAPI to authorise a licence policy.

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

pLicence
Points to a licence policy structure.

pChallenge
Points to a challenge structure. The licence system does not challenge back.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Remarks

If an application wants to issue a licence policy programmatically without the user’s involvement, this is the function to call. This function is typically used by an application’s installation program to issue an evaluation licence with a limited licence policy.

The input parameter for computing challenge is the Licence structure.

Request Licence

HRESULT SLS_Request(LPCSTR pszProductID,LPCTSTR pszUserName,SLS_REQUEST *pRequest,
SLS_PERMIT *pPermit,SLS_HANDLE *plLicenceHandle,SLS_CHALLENGE *pChallenge)

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

pszUserName
Points to a string uniquely identify the user’s name.

pRequest
Points to a request structure.

pPermit
Points to a permit structure to receive permission granted by the licence system.

plLicenseHandle
Points to an SLS_HANDLE in which a handle to the licensing context is returned.

Challenge
Points to a challenge structure. The challenge response will also be returned in this structure.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

The typical error status codes are:

SLS_E_LICENCE_UNREGISTERED
SLS_E_LICENCE_UNDEFINED
SLS_E_LICENCE_EXCEEDED
SLS_E_LICENCE_EXHAUSTED
SLS_E_LICENCE_EXPIRED
SLS_E_LICENCE_INVALID

Remarks

Use the SLS_Request function to request the licensing system to grant permission to the identified product to execute. If a valid licence is found, the challenge response is computed and SLS_SUCCESS is returned. A licence handle is also returned by the licence system to identify licensing resources allocated to the user. The application must call SLS_Release to free the licensing resources.

A challenge response is not returned unless the licensing request completes successfully. If SLS_Request fails, the licence handle is set to 0, therefore there is no need to call SLS_Release.

The input parameter for computing challenge is the Request structure; the output parameter for computing challenge is the pPermit structure

Update Licence

HRESULT SLS_Update(

LPCSTR pszProductID,
SLS_HANDLE lLicenceHandle,
SLS_UPDATE *pUpdate,
SLS_PERMIT *pPermit,
SLS_CHALLENGE *pChallenge)

The SLS_Update function reports the up-to-date licence usage to the licence system and synchronizes between the licensed application software and the licence system.

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

lLicenseHandle
Specifies the handle to the licensing context. This parameter must be a handle created with the SLS_Request function.

pUpdate
This parameter is used only if a policy is in effect that consists of unit metering licences (and if you choose to implement such a licensing policy in the application). The UnitsConsumed parameter in the Update structure specifies the total number of units consumed in this handle context since the initial call to the SLS_Request function. The UnitsReserved parameter specifies the total number of units to be reserved.

pPermit
Provided a structure for receiving licence permit. Permit data members are explained in the Permit data structure.

pChallenge
Points to a challenge structure. The challenge response will also be returned in this structure.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

The typical error status codes are:

SLS_E_LICENCE_SUSPENDED
SLS_E_LICENCE_EXCEEDED
SLS_E_LICENCE_EXHAUSTED
SLS_E_LICENCE_EXPIRED
SLS_E_LICENCE_INVALID

Remarks

Your application should periodically call the SLS_Update function to verify that the current licence is still valid. The maximum interval is 30 minutes.

The SLS_Update function verifies that the licence system context has not changed from the one expected by the licensed software. The SLS_Update function can determine if the licensing resources granted to the specified handle are still reserved for this application. In a distributed licence system, an error might indicate a temporary network interruption. It can also determine if the licence system has released the licensing resources granted to the specified handle. An error indicates the software no longer has authorisation to execute in a typical manner.

The call to the SLS_Update function can also indicate that the current licensing context has expired. For example, in the case of a time-restricted licensing policy it returns the warning status SLS_LICENSE_EXPIRED.

If the number of new units requested in the Update.UnitsReserved parameter is greater than the number available, then the update request fails and it returns the error SLS_LICENCE_ EXHAUSTED.

If the call completes successfully, the value returned in the Permit.UnitsGranted parameter indicates the current total of units granted.

If SLS_Update returns an error, it does not return a challenge response.

If any error is returned, a call to the SLS_Release function is still required.

Release Licence

HRESULT SLS_Release(

LPCSTR pszProductID,
SLS_HANDLE lLicenceHandle,
SLS_RELEASE pRelease,
SLS_CHALLENGE pChallenge)

The SLS_Release function requests that the licence system release the licensing resources associated with the licensing context identified by the lLicenseHandle parameter.

Parameters

pszProductID

Points to a string that uniquely identifies the application’s Product ID.

lLicenseHandle
Specifies the handle to the licensing context. This parameter must be a handle created with the SLS_Request function.

pRelease
Specifies the total licence usage. This parameter is used only if a licence policy is in effect that comprises of unit metering (and if you choose to implement such a licence policy in the application). The UnitsConsumed parameter in the Release structure specifies the total number of units consumed in this handle context since the initial call to the SLS_Request function.

pChallenge
Points to a challenge structure. The challenge response will also be returned in this structure.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Remarks

Use the SLS_Release function to release licensing resources associated with the licence context identified by the lLicenseHandle parameter.

Create Challenge

HRESULT SLS_CreateChallenge(

SLS_SECRET *pSecretArray,
int nSecrectSize,
const BYTE *pbStream,
int nStreamSize,
SLS_CHALLENGE *pChallenge)

The SLS_CreateChallenge function creates a challenge from the input data stream.

Parameters

pSecretArray
Points to an array of product secrets.

nSecretSize
Size of the secret array.

pbStream
Points to the buffer of input data stream.

nStreamSize
Size in byte of the input data stream buffer.

Challenge
Points to a challenge structure in which the challenge will be created.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Verify Challenge

HRESULT SLS_VerifyChallenge(

SLS_SECRET *pSecretArray,
int nSecrectSize,
const BYTE *pbStream,
int nStreamSize,
SLS_CHALLENGE pChallenge)

The SLS_VerifyChallege function verifies the specified challenge.

Parameters

pSecretArray
Points to an array of product secrets.

nSecretSize
Size of the secret array.

pbStream
Points to the buffer of input data stream.

nStreamSize
Size in byte of the input data stream buffer.

pChallenge
Points to a challenge structure from which the challenge will be verified.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error. Two possible errors are SLS_E_CHALLENGE_UNSUPPORTED and SLS_E_CHALLENGE_ILLEGAL.

SetOptions

HRESULT WINAPI SLS_SetOptions(

LPCSTR pszProductID,
SLS_HANDLE lLicenceHandle,
SLS_OPTIONS *pOptions,
SLS_CHALLENGE *pChallenge)

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

lLicenseHandle
Specifies the handle to the licensing context. This parameter must be a handle created with the SLS_Request function.

Options
Points to an options structure.

pChallenge
Points to a challenge structure from which the challenge will be verfied.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Terminate Licence

HRESULT WINAPI SLS_Terminate(LPCSTR pszProductID, LPSTR pszTerminationCode)

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

pszTerminationCode
Points to a string containing the termination code .

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Remove Licence

HRESULT WINAPI SLS_Remove(LPCSTR pszProductID, DWORD dwOptions,SLS_CHALLENGE *pChallenge)

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

dwOptions
Instructs how which part of the licence system should be removed. It is a combination of the following values:

#define SLS_REMOVE_FILES 0x0001 //remove licence files

#define SLS_REMOVE_REGISTRY 0x0002 //remove licence registry

#define SLS_REMOVE_HISTORY 0x0004 //remove licence history

#define SLS_REMOVE_ALL 0x0007 //remove all of above

pChallenge
Points to a challenge structure. The licence system does not challenge back.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Remarks

Unlike SLS_Terminate which is intended for end users to terminate the licence, SLS_Remove is intended for the software publisher to remove the licence. The difference between "Terminate" and "Remove" is that (a) SLS_Terminate generates termination code that the software publisher can ask to verify whether the licence has been terminated from the PC, whereas SLS_Remove does not. (b) SLS_Terminate only removes the licence files, whereas SLS_Remove can completely remove all of the licence’s components including licence files, registry setting and history marks on the PC.

Export Licence

HRESULT WINAPI SLS_ExportLicence(

LPCSTR pszProductID,
LPCSTR pszReference,
SLS_LICENCE *pLicence,
LPSTR pszLicenceKey)

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

pszReference
Points to a string that contains the reference code that is obtained from the PC to which the licence is being exported.

pLicence
Points to a licence policy structure.

pszLicenceKey
Points to a buffer in which the Licence Key is to be placed. The minimum size of the buffer is 64 bytes.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Import Licence

HRESULT WINAPI SLS_ImportLicence(

LPCSTR pszProductID,
LPCSTR pszReference,
LPCSTR pszLicenceKey)

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

pszReference
Points to a string that contains the reference code that is obtained from the PC to which the licence is being exported.

pszLicenceKey
Points to a string that contains a exported licence key returned by calling SLS_ExportLicence.

Get Licence Status

HRESULT WINAPI SLS_GetStatusCode(LPCSTR pszProductID, LPSTR pszStatusCode)

Parameters

pszProductID
Points to a string that uniquely identifies the application’s Product ID.

pszStatusCode
Points to a buffer in which the Status Code is to be placed. The minimum size of the buffer is 32 bytes.

Return Values

SLS_SUCCESS if the function is successful. Otherwise an error status code is returned to indicate the cause of the error.

Remarks

Use the SLS_GetStatusCode function to retrieve the current status of the licence. A licence policy might have been modified by the user by exporting, this function provides the publisher a way of checking the current licence status and verifying it. Licence status is returned in the form of 40-digit code.

Request for Licence (Extended)

HRESULT SLS_RequestEx(LPCSTR pszProductID,

LPCTSTR pszUserName,

DWORD dwUserID,

SLS_REQUEST *pRequest,

SLS_PERMIT *pPermit,

SLS_HANDLE *plLicenceHandle,

SLS_CHALLENGE *pChallenge)

Extended version of SLS_Request with extra parameter dwUserID which can be used by the application to provide extra information about the user. The user ID can be retrieved back by calling SLS_QueryUserInfo.

Get User Count

HRESULT WINAPI SLS_GetUserCount(LPCSTR pszProductID,DWORD *pdwUserCount);

SLS_GetUserCount returns the total number of users who are using the product specified by the pszProductID. The user count is returned to the buffer pointed by pdwUserCount.

Get User Count

HRESULT WINAPI SLS_QueryUserInfo(LPCSTR pszProductID,DWORD dwUserIndex,SLS_USER_INFO *pUserInfo);

SLS_QueryUserInfo is called to retrieve information of the users who are using the specified product. dwUserIndex is the index number of the user, its value is between 1 and the user count returned by SLS_GetUserCount. *pUserInfo points to a SLS_USER_INFO data structure to receive the information.

Set/Get Publisher Data

HRESULT WINAPI SLS_SetPublisherData(LPCSTR pszProductID,LPCTSTR lpszPublisherData);

HRESULT WINAPI SLS_GetPublisherData(LPCSTR pszProductID,LPTSTR lpszPublisherData);

Although Sheriff provides a comprehensive set of licensing features including time/unit metering, expiration control and feature access level, sometime publishers might want to control their licences in some kinds of special ways that would be difficult to implement with the standard features. Publisher data is designed for this purpose. Publisher data is simply a space up to 32 bytes that Sheriff uses to keep any data that publishers might specify. The format and meaning of the data is up to the publisher to interpreter.

Publisher data is kept together with the product’s licence key in the licence file. It is set by calling SLS_SetPublisherData and retrieved by calling SLS_GetPublisherData.

Others

HRESULT WINAPI SLS_IsProductInstalled(LPCSTR pszProductID);

HRESULT WINAPI SLS_IsProductLicensed(LPCSTR pszProductID);

IsProductInstalled returns SLS_SUCCESS if Sheriff detects that the specified product has been installed on the PC.

IsProductLicensed returns SLS_SUCCESS if Sheriff detects that the specified product has been licensed on the PC.

Note that both functions are meant to detect the history of the product and licence. A success return does not necessarily mean the current state of the product or licence on the PC. In other words, if the specified product was installed or licensed once on the PC and then terminated or deleted, SLS_IsProductInstalled or SLS_IsProductLicensed will still succeed.

These functions are typically used in applications to prevent users from re-installing a trial licence.


 Installation

How compatible is Sheriff with InstallShield?
InstallShield can call a Windows DLL, so it can also call Sheriff. Just call the Sheriff DLL from your InstallShield script code.

In a competitor product there have been instances where it couldn't retrieve a volume name or number when installing and security was breached allowing the installer to install yet another copy of the same software. Do you know if your product might encounter this problem?
No, volume number is only one of the parameters that Sheriff uses to generate the machine fingerprint. The algorithm that Sheriff uses to uniquely identify a machine is much more sophisticated than simply checking for the hard disk volume number.


 Serial Numbers & Product IDs

One Serial Number creates a single, unique Product ID. If I have more than one product, do I need more than one Product ID?
Generally, yes. If you had only one Product ID then if more than one product was installed on a single machine each product would have to share the same Licence Policy.

How many Licence Keys can I distribute for my product and do I have to pay a royalty?
Once you have purchased a Serial Number for your product you can issue an unlimited number of Licence Keys without any further payment.

Upon purchase of the full product is there any additional documentation, examples etc. or is everything provided with the evaluation kit?
Everything is included in the evaluation kit.


Demo & Upgrade Licences

If we put our software on our web site, can we use Sheriff to control rights based on how long users should use the software demo after downloading it from our web site?
You can use Sheriff to control rights based on how long they can use the software after they have installed it - it is not possible to control their use of the software from the time they download it.

I need to have the capabilities to authorise a distributor to open my software n times only within 30 days. Is this possible?
Yes, you can combine 'date' and 'unit' metering to achieve this result.

When a user tries to install my program on another machine, the application should revert back to "demo" mode with specific function(s) turned off. Is this possible?
It depends on how the application defines “demo” mode. For example, the application could be coded so that if there is no valid licence found then it runs in demo mode automatically.

I am looking for a software only licensing solution. We are issuing multiple versions of our software and would like to let our customers purchase "limited upgrades", for example if a customer has 10 licences purchased, he can upgrade only 2 of them. The licensing program must be "smart" enough to let only 10 copies of the program run simultaneously, of which maximally two can be newer, upgraded version. Can this be done with your software?
Sheriff can be used to limit the number of concurrent users. Through the Sheriff API, you can check the number of active users at any time. If you decide that only 2 users out of 10 can run in full feature mode and the rest in trial mode, you can query Sheriff for the active users to check whether the number of active users is less than 2 and decide whether the current instance should be running in full mode or trial mode accordingly.


 Managing Licence Keys

How is the licensing of different versions of an application handled?
'Feature access control' can be used to control versions of an application.

Each application on our CD should have its own token (should be protected independently regardless of the other applications). Is this possible?
Yes. Each application should have its own unique Sheriff Product ID. This is used to distinguish that product from other Sheriff-protected products and permits multiple protected products to be installed on a single machine.

Is it possible for multiple applications to be activated all at once or one by one at different periods of time.
There is no problem with this as the protection for each app is independent (i.e. each has its own Product ID). Multiple users and applications are administered by the end user using the Sheriff Licence Administrator application (SlsAdmin.exe).

If the user needs to move the application to another machine, will they will have to call the publisher?
No, this is not necessary as there is an export procedure that enables a user to move the Licence Key to another machine without contacting the publisher (although there is an option to disable this). Please see the Administrator Help for further details.

Is the transfer of a protected application between two different PCs software oriented or is an external element (i.e. floppy disk) required?
The export of a licence key from one machine to another is entirely via software. The user generates a code on the import machine (similar to a Reference Code) and this is then validated by the exporting machine. The user uses the Sheriff Licence Administrator program to do this.

If we need to have a pre-determined Licence Key (like the CD-Key in most Microsoft products) with a 'Expiry Date' and 'Number of User' set, is it possible?
No, because the Licence Key is unique to each system it has to be created on the system itself. However it is possible for a Licence Key to be created on installation (i.e. self-generated) without reference to the publisher, although this is less secure.

When registering products using the Sheriff Licence Key Generator and subsequently issuing customer Licence Keys is all this information kept on a permanent basis on the computer that is using the Sheriff Licence Key Generator EXE file (SlsGen.exe)?
Yes, the information about licence keys that you, the publisher, have issued is kept in a log file and there's no problem about backing up or restoring this - or the Sheriff Licence Generator (SlsGen.exe) - to another machine.

Can we keep a copy of the licence keys granted to the customer in the event that there is a system catastrophe at the customer's site and we can get them up and running again in a very short time and with the absolute minimum of fuss?
If your customer has an unrestricted licence (i.e. the licence is not metered and does not expire) you can give them a 'Reusable' key. If they make a note of the key number then they can restore the licence even after a disk crash PROVIDED that their hardware remains the same and the hard disk has not been reformatted.

Are there any limitations imposed on making backups of a hard disk or other similar system maintenance operations?
It is not possible to backup and restore the licence file since this could compromise security.

My customer says he wants to upgrade his hardware and he needs another licence for the new system - how do I know he's telling the truth?

  1. You can ask him to terminate the existing licence first. Using the termination facility provided by the Sheriff Licence Administrator (SlsAdmin.exe) he informs you of the termination code; you use the Sheriff Licence Generator (SlsGen.exe) to verify whether he has actually terminated the existing licence before issuing a new licence key.
  2. It is possible to tell whether a new Reference Code has been generated on the original hardware by comparing the first twelve digits of the code (the machine signature) with the original Reference Code. If the machine signature is the same then the hardware is unchanged.

One problem we have had to deal with in the past is when we get a phone call/email saying from a customer saying that "our disk crashed, send us another key". Many times, we had no way to check it out. We had to give another key. What do you do in this case?
You will note that the User Reference Code is 24 digits. The first 12 digits are the user's machine signature, the next 4 are the product signature and the remaining 8 are the run-time signature. Thus it is possible to tell whether two Reference Codes are generated from the same machine by comparing the machine signature.

Do I have to ask the customer for a Reference Code every time I issue a new key?
Not if you use Expiry Date metering. There is an option that enables you to issue a 'Reusable Reference Code' so that when the software expiry date draws near you can issue a new key without any need to contact the customer.

If my customer wants to change his hardware, how does he do this?
Your customers can change any hardware component other than motherboard components - although they can upgrade RAM - or hard disk . Should they want to upgrade the motherboard or hard disk they can either temporarily export the licence to another machine or else you must issue them with a new licence key.

My customer wants to upgrade his operating system - can he do this without asking for a new licence key?
Yes, upgrading the o/s does not require any special precautions. If the o/s needs to be reinstalled from scratch then the current licence must be terminated and the customer must be issued with a new key. Alternatively, the existing key can be checked-out to another machine then then checked back in again when the new o/s has been installed.


 Network Licences

Is there the possibility of defining the maximum number of concurrent users on a LAN?
You define the maximum number of concurrent users with the Sheriff Licence Generator application (SlsGen.exe) when you issue a licence key.

You say that any network operating system is supported. Could you clarify?
You can run Sheriff over a network but Sheriff isn't aware of the Network Operating System or protocol (E.g. Netware / IPX etc.). For a network licence you will need to have the licence file accessible in a shared location (E.g. file server) and each workstation that's running the Sheriff-protected application will need to be able to share (i.e. have access to) that licence either using drive mapping or UNC.

Does Sheriff create much additional network traffic if there are many network users (E.g. 100 concurrent users)?
No. The extra traffic created by Sheriff is minimal. It is only the heat-beating message, which is a very small packet in size.

Is the only way to add new network licences to a licence file by terminating the current licence and issuing a new licence key?
Yes. To alter the licence policy a new licence key has to be issued.

How is the user's name encoded into the licence?
User's name is not encoded in licence key - the machine signature ('digital fingerprint') is encoded.

I am wondering how counting works. I presume that it counts concurrent users regardless of the identities of these users?
Sheriff counts concurrent users regardless of their identity. Normally your Sheriff licence database will be located on a server to which all prospective users will have write access. This is a typical network configuration where the licence file is locked to a server to which network users have access. It is often referred to as a "floating" licence configuration because as long as the maximum number of users is not exceeded, any user who has access to the licence file on the server can run the application. When a user terminates the application then the number of available licence is incremented by one.

With floating licences, you specify the maximum number of concurrent users (i.e. the maximum number of users who can simultaneously run your application). An alternative configuration is called "standalone", where the protected application can only run on the machine on which the licence file is installed.

What I cannot understand is that the key seems to be machine-specific. Does that mean that if we sell a 50-user license each potential user (i.e. in general many more than 50) has to call us to get a key? Also, if another user happened to buy a single-use license and runs it on the same network, would he interfere with the 50-user license count?
In a situation where you have 50 network users and you want to add another ten users, you will have to issue a new licence key to cover these additional users. So if you wanted to license a total of 60 users, you would issue a replacement key for 60 users (the new key overwrites the old key rather than incrementing it).

If you licensed a single additional user - Fred - on the network you could either issue a new key for the server (as in the example above) or you could issue a standalone key for Fred's workstation. Fred would install your software on his own workstation and the Sheriff licence database would reside on that machine (the fact that the machine happened to be connected to a network would be irrelevant). In this example the other network users would not be able to share Fred's licence (so the answer is "No", Fred's licence would not interfere with the 50 licence count).


FAQ The Sheriff API

 The Sheriff API

Can I use Sheriff to protect my application without resorting to C++?
Yes, SlsApi.dll is a standard Windows DLL that can be called by any Windows programming language including Delphi, Visual Basic and VBA. In fact, Sheriff SDK provides ready-to-use templates/classes for Delphi, Visual Basic & Visual FoxPro.

What library and header files will I need to include in my project?
It depends on your programming language. In Sheriff SDK there are three directories under the API directory, namely VC, VB, Delphi & VFP. In general you have to include all of the files from the relevant directory in your project. To distribute your software, you only need to include SlsApi.dll.

I understand that it is possible to bypass the need for the user to call in for a licence number, using the SLS_License function?
SLS_License is designed for issuing trial/demo licence only. Although it does not stop you from using to issue a full licence, we do recommend that user has to contact you for a proper Licence Key. However, your contact can be made by phone, fax, email or even your web-site (with Sheriff 1.61 and above you can set up a web page that can automatically issue licence keys, though this requires an NT server).

Can there be "soft" and "hard" landings, meaning the user gets a warning when they are approaching their limits of logons?
Yes, how your application behaves when the limit is approaching is decided by your application. By using the API function SLS_GetLicenceInfo you can retrieve the states of the licence, including the usage, at any time.

I've tried to install my protected software and then to change the system clock to extend the time. The Sheriff API detected the time change but now, each call to SLS_GetReference generates an error message : "Invalid System Time" and the software is then locked for eternity. What's happening?
As soon as Sheriff detects any system or licence parameter being tampered with it locks up the licence database to prevent further usage. The way to unlock your licence database is to either change your system clock back to the correct time or delete the licence database files and start it again. Please note that Sheriff allows up to 24 hours time difference between workstations.

Monitoring the registry in Windows NT shows that upon registering an application registry entries are created pointing to the location of the licence files. Thus if the registry entries and licence files are deleted it appears to be possible to reset any demo version of software and begin the demo period again. Is there any mechanism which will detect this occurrence and provide protection against this action?
Function SLS_IsProductInstalled is provided for this purpose. Before calling SLS_License to issue a demo licence, call SLS_IsProductInstalled to check whether the product has been previously installed. Sheriff Ver 1.1 and above enhance this feature to provide additional protection against re-installing a demo licence.

You have indicated that the API function SLS_IsProductInstalled prevents users from installing multiple times on the same PC (or, I assume, same network). Is there, however, a means of preventing multiple installations to other PC's? Is that what is meant when it generates a machine "fingerprint"?
When a Sheriff-protected product is installed on a particular machine it is bound to that machine, which can identified by my means of the machine 'fingerprint' contained in the unique Reference Code that is displayed at the time of installation. Normally, a user will quote their Reference Code to you, the publisher, and you will issue a Licence Key to the user enabling him to run the application according to the terms of the Licence Policy (unlimited use, unit metered etc.). However, because the application is bound to the machine that it is installed on, it cannot be copied from that machine to other machines. It can, however, be installed to other machines provided the correct installation procedure is undertaken (i.e. the publisher issues a unique Licence Key for each of those other machines). So it's up to you to decide how many machines the application is installed on. SLS_IsProductInstalled function is typically used in conjunction with SLS_License. SLS_License will be used only when you wish to issue a trial licence with some limitations - such as limited features or limited life span.


Sheriff - EULA

Sheriff User Agreement

You should read carefully the following terms and conditions of the User Agreement in its entirety before either downloading, installing, integrating, evaluating or using the Sheriff software and/or components. Do not download, install, integrate, evaluate or use the software unless you agree to be bound by the definitions, terms and conditions of this Agreement.

An Agreement between Acudata Limited of Clarendon House, Shenley Road, Borehamwood, Hertfordshire, WD6 1AG, England (hereinafter referred to as "AD") and the software user (hereinafter referred to as "the user").

Whereas AD is a company based in the United Kingdom in the business of software development and related services and has designed and developed a suite of software applications, known as collectively as "Sheriff", used by software publishers and developers to restrict the unauthorised copying of software applications and the user wishes to make use of Sheriff for this purpose

Now it is hereby agreed as follows:

Definitions

The term "Software" shall refer to the files supplied via electronic download or on diskette(s) or other media and/or to any and all copies, upgrades, modifications, versions, editions, functionally-equivalent derivatives, or any parts or portions thereof, including any electronic, on-line or printed documentation. The term "Software" includes the Sheriff Serial Number, Product ID and Secret Codes.

Unless stated otherwise the term "Sheriff" shall include all components of the suite of software programs known as the Sheriff Software Development Kit (The "Sheriff SDK") including, but not limited to, all files, code, libraries, executables and documentation.

"Install" means the action of loading the software onto a permanent storage device (such as a hard drive).

"Use" means to run the software by loading into such computer's temporary memory.

Grant of Licence

AD hereby grants the user a non-transferable, nonexclusive license to use the software on the terms and conditions contained herein.

Term of Licence

This Licence is effective until terminated, either expressly or by implication, by the either AD or the user.

Ownership of Software

AD is the sole owner of the software and all rights not specifically granted in this licence are reserved by AD.

The Users' Obligations

The user warrants that all information supplied to AD concerning the identity, address and other details of the user shall be true and that any additional information that can be reasonably considered relevant to the terms of this Agreement shall be disclosed by the user to AD, whether or not AD has specifically requested such information.

Under this licence the user agrees to:

  • Except as otherwise provided for in this Agreement, keep all copies of the software solely in his/her possession.
  • Use reasonable efforts to protect the software from unauthorised use, reproduction, publication or distribution.
  • Use the software only for the purpose set forth in this Agreement and for no other purpose.
  • Without charge transfer to AD all property in any comments, reports of difficulties or problems with the software and all suggestions for improvement.

Under this licence the user may not:

  • Distribute the software, except as provided for under the terms of this Agreement.
  • Sublicense, rent, lease, lend or otherwise transfer the software or the user's rights under this licence without the prior written consent of AD.
  • Inform, directly or indirectly, any third party of the the user's unique Serial Number, Product ID or Secret Codes.
  • Remove or obscure any copyright and trademark notices.

Software Installation

The software may be installed and used on any computer that is owned or normally used by:

  • the user
  • the user's customer(s)
  • an employee of the user or the user's customer(s)

PROVIDED THAT where the user integrates Sheriff with a product (application, database etc.) belonging to the user's customer(s):

  • the user shall give notice to the customer(s) of the terms of this Agreement and the customer(s) shall likewise be bound by its terms.
  • the user shall purchase a separate (full-price) Serial Number for each of the user's customers.
  • where a customer of the user has more than one product, the user shall purchase an additional (discounted) Serial Number for each additional product.

Sheriff Licence Administrator Application

Notwithstanding the terms of this Agreement, the Sheriff Licence Administrator application (SlsAdmin.exe) and its associated documentation may be freely distributed without any restriction whatsoever.

Applications Not Developed by AD

AD makes no proprietary claims of any kind, whether in copyright or otherwise, to any software applications developed by the user for either the user or any customer of the user.

Contractual Relations with the User's Customers

Any contractual arrangement that exists between the user and his/her customers shall not extend to AD and the user hereby agrees to indemnify and hold AD harmless against any claim, expense, loss, damage, or other liability, including (but without limitation to) legal fees, arising out of or connected with the customer's use of the Sheriff Licence Administrator, the Sheriff Licence Generator and/or their associated components.

Support of Software

For a period of 90 days following the date of this Agreement AD shall provide the following support:

  • Unlimited support by electronic mail (email)
  • Free software upgrades
  • Free bug fixes

After the period of 90 days has elapsed AD shall have no further support obligations of any kind under this Agreement and such support services as AD supplies to the user shall be under the terms of the ancillary Sheriff Software Support & Maintenance Agreement, the terms of which shall be supplemental to the terms of this Agreement.

Any supplemental software code and/or documentation provided as part of the Support Services shall be considered part of the Software and subject to the terms and conditions of this Agreement. With respect to technical information provided to AD as part of the Support Services, AD may use such information for its business purposes, including product support and development.

Return of Software upon Termination.

At the end of the term of this licence or upon termination by either party the user shall either destroy or immediately return all copies of the software to AD unless otherwise agreed.

Upgrades & Bug Fixes

After a period of 90 days has elapsed AD is under no obligation to provide the user with upgrades to the software or to inform the user when upgrades are available otherwise than under the terms of the Sheriff Software Support and Maintenance Agreement.

The user accepts that the circumstances under which software products are deployed can vary widely and that it is impossible for AD to envisage all of these circumstances. Situations may arise in the field in which defects in the software ('bugs') are uncovered. The user accepts that the only remedy is to inform AD of the nature of the problem and the circumstances under which it arose. AD shall then take all reasonable steps to remedy the problem within a reasonable period of time. The user accepts that in some cases it may not be possible to remedy the defect due to the unique nature of the circumstances under which the software has been deployed.

Disclaimer of Warranties and Limitation of Remedies

"Unregistered software" is software that is supplied to the user free of charge (i.e. without monetary payment by the user). The user acknowledges that unregistered software is being made available to the user on an AS IS BASIS FOR EVALUATION PURPOSES ONLY, and that AD makes no warranties, express or implied, with respect to the software.

Purchase of a Serial Number registers the software and indicates that the user is satisfied that the software is suitable for his/her requirements. AD cannot provide refunds after registration. Orders for Serial Numbers are filled immediately – once placed, they cannot be cancelled.

AD specifically disclaims all implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose. It is for the user to evaluate and test the software and to determine its capabilities.

In no event will AD be liable for special, incidental or consequential damages arising from the use, or inability to use, the software, even if AD has been advised of the possibility of such damages. In particular, AD shall not be liable for the loss of information or data arising from the use or inability to use the software either by the user or the user's customers.

In all cases AD's maximum liability for any claim arising from the licence or use of the registered software, including but without limitation to claims based upon AD's negligence, shall be limited to the replacement value of a single copy of the software. The remedy set forth above is exclusive and in lieu of all others, oral or written, expressed or implied.

No developer, distributor, employee, or agent is authorised to extend any warranty or modify or extend the above remedy in any manner.

Indemnification

The user acknowledges that its use of the software is personal to the user and is not intended to be used for the benefit of any third party (other than the user's customers). The user shall indemnify and hold AD harmless against any claim, expense, loss, damage, or other liability, including (but without limitation) legal fees, arising out of or connected with the user's use of the software under this Agreement.

Remedies for Breach

In the event that the user breaches any warranty, covenant or other term of this Agreement, whether express or implied, AD shall be entitled to immediately terminate this Agreement and the licence hereunder and to seek all legal and equitable remedies available to it.

The user acknowledges that breach of any of the terms of this Agreement may result in irreparable and continuing damage to AD in an amount not readily ascertainable and for which there would be no adequate remedy at law. In the event of such a breach, AD shall have the right to seek immediate injunctive relief, in addition to its other remedies hereunder.

Non-Waiver

The failure or delay of any party to require performance of, or to otherwise enforce, any condition or other provision of this Agreement shall not waive or otherwise limit that party's right to enforce or pursue remedies for the breach of any such provision or condition. Any waiver by any party of any particular condition or provision of this Agreement, including this non-waiver provision, shall not constitute a waiver or limitation on that party's right to enforce performance or pursue remedies for the breach of any other condition or provision of this Agreement.

Severability

If any court of competent jurisdiction finds any term of this Agreement, or of any other document or instrument referred to or contemplated in this Agreement, to be invalid or unenforceable, such determination shall not affect the validity and enforceability of the remainder of the Agreement.

Paragraph Headings

All paragraph headings in this Agreement appear for convenience of reference, and shall not affect the meaning or interpretation of the Agreement.

Assignment

This Agreement may not be assigned by the user without the prior written consent of AD. Subject to this restriction, this Agreement is binding upon and shall inure to the benefit of the heirs, successors, assigns, legatees, devisees, bankrupt estates, administrators, personal representatives and executors of each of the parties.

Governing Law

This Agreement shall be governed by and construed in accordance with the Laws of the England & Wales.

Amendments

This Agreement may be amended or modified only by a written instrument executed by the parties that expressly states the intent of the parties to modify or amend this Agreement.

Entire Agreement

This Agreement constitutes the entire agreement between the parties pertaining to the subject matter of the Agreement and supersedes all prior discussions, negotiations, understandings, representations and agreements, whether oral or written. All terms of this Agreement are contractual and not mere recitals.

Electronic Execution

Execution of this Agreement may be evidenced by downloading, installing or using the software.

Version 2.4
22 June 1999


Sheriff Software Support & Maintenance Agreement

An Agreement between Acudata Limited of Clarendon House, Shenley Road, Borehamwood, Hertfordshire, WD6 1AG, England (hereinafter referred to as "AD") and the software user (hereinafter referred to as "the user").

Whereas AD is a company based in the United Kingdom in the business of software development and related services and has designed and developed a suite of software applications, known as collectively as "Sheriff", and the user has entered into a licensing agreement ('Sheriff User Agreement') with AD for the use of Sheriff

Now it is hereby agreed as follows:

In addition to any pre-existing obligations under the Sheriff User Agreement AD shall, for a period of one year from the commencement of this Support & Maintenance Agreement, supply to the user the following services

  • Provide access to all maintenance and other upgrades - including major version upgrades - without charge and shall inform the customer as soon as such versions and upgrades become available.
  • Provide the customer with guaranteed 24 hour response by email to communications from the customer.
  • Use all reasonable endeavours to replace any defective materials and resolve customer reported software defects and report promptly and regularly to the customer on all steps being taken to rectify such faults.

(Version 2.3)


Activating a Product

Activating a product is a two step procedure:

1. The user generates a Reference Code for the publisher using the Sheriff Administrator (SlsAdmin.exe)
2. The publisher issues the user with a Licence Key using the Licence Key Generator (SlsGen.exe)

The Reference Code consist of 24 digits. The first 12 digits are the user's machine signature, the next 4 digits are the product signature and the remaining 8 digits are the run-time signature. It is possible to tell whether or not two Reference Codes are generated from the same machine by comparing the machine signatures.

The user (U) must generate a Reference Code on the hardware for which the product is to be licensed. The Reference Code may be generated as part of the installation process or separately using the Sheriff Administrator. The steps shown below assume the user is using the Administrator but if this is not the case simply omit this stage.

Administrator

  • U opens the Product Registry by selecting Licence | Registry (or by clicking the Registry button on the toolbar).

  • The Registry displays details of the registered products, including Product ID and Licence Path.
  • U selects the product and clicks on the License button and the License Product dialog box displays the Reference Code.
  • U informs the publisher of the Reference Code.

Licence Key Generator

  • P enters the user's name.
  • P selects the appropriate product from the drop-down list.
  • P enters U's Reference Code.
  • P defines the licence policy by enabling the licence features and selecting the options.
  • P clicks on the Generate button to produce a Licence Key for the User.
  • U enters the Licence Key in the Licence Product dialog box and clicks Save. The product is now activated.


Contact/Purchase

Acudata Limited
Clarendon House
Shenley Road
Borehamood
Hertfordshire
WD6 1AG
England

Web: http://www.sheriff-software.com
Email: info@sheriff-software.com

Tel: +44 181 905 2552
Fax: +44 181 959 8583

Purchase

Purchase on the Web
Email a sales enquiry

US Customers can also order by phoning RegNet on 1 800 999 2734 and quoting product #2689. (Note: only phone this number to place an order).


Product ID [GEN]

Product ID

A 20 digit code that identifies a particular product. The publisher generates a Product ID by entering a Serial Number in the Sheriff Product ID and Secret Codes Generator (SlsPsn.exe). To evaluate Sheriff, use the evaluation Product ID shown in this help file.


Reference Code [GEN]

Reference Code

Consists of 24 digits. The first 12 digits are the user's machine signature, the next 4 digits are the product signature and the remaining 8 digits are the run-time signature. It is possible to tell whether or not two Reference Codes are generated from the same machine by comparing the machine signatures.


Secrets Codes [GEN]

Secret Codes

Prevent third parties from generating licence keys for your product - even if they have a Licence Generator - and are also used to encrypt the communication channel between the application and Sheriff, so providing unique encryption for every product. You generate Secret Codes at the time of generating the Product ID, using the Sheriff Product ID and Secret Codes Generator (SlsPsn.exe). You can use either the numeric or encrypted Secret Codes.


System Architecture

Sheriff comprises four components:

  • Client
  • Server
  • Registry
  • Licence Database

Client

Client is the application you wish to protect. Client interacts with the licence server through API functions.

Server

Server is the Sheriff DLL i.e. SlsApi.dll, which provides licensing services through its API functions.

Registry

Sheriff utilises the Windows Registry to keep track of various licences and the location of licence databases on the user’s machine.

Licence Database

The Sheriff licence database maintains information such as licence policy, licence usage and user’s activities.